Every box in a homelab eventually needs to tell you something: a backup failed at 02:00, a disk crossed 90%, a service stopped answering. A self-hosted ntfy Docker stack gives all of them one place to send that message with a single curl, and gives your phone one place to listen. The public ntfy.sh server does the same job, but your topic names and message bodies then live on a server you do not control, and its free tier stops at 250 messages a day.
This guide builds a private ntfy server with Docker Compose behind Caddy for HTTPS, locks it down with auth-default-access: deny-all, users, topic ACLs and an access token, and then wires up four real senders: plain curl, a bash backup script, Gatus and borgmatic. We also cover the iOS upstream relay and what self-hosting costs against ntfy.sh Pro and Pushover. I ran through all of it on Ubuntu 26.04 and 24.04 VMs in my homelab in November 2026 with ntfy 2.37.2, and every output below comes from those boxes.
How the ntfy Docker stack fits together
The design rule we followed is simple: only Caddy publishes ports on the host. The ntfy container listens on port 80 inside the Compose network and never sees the internet directly, so TLS, HTTP/3 and the client IP header all come from one place. Gatus, borgmatic and the backup script run on the same VM in the lab, but they talk to ntfy through the public HTTPS name exactly like a sender on another machine would.

The snag in the corner of that sketch is the one thing that cost us time in the lab, and Step 7 shows the exact error. Everything else worked on the first run.
What you need
ntfy is tiny. With Caddy and Gatus running beside it, the three containers used 32 MiB of RAM between them on our VM, so the sizing is driven by everything else you run on the host, not by ntfy. A small VM, a Raspberry Pi or a corner of an existing Docker host is plenty for a homelab:
- Ubuntu 26.04 or 24.04 with sudo access (we used 2 vCPU and 4 GB RAM)
- A DNS name for the server, for example
ntfy.example.com - Ports 80 and 443 reachable if you want a public ACME certificate
- About 300 MB of disk for the ntfy, Caddy and Gatus images
Our lab VMs sit on a private LAN with no public DNS, so Caddy issued the certificate from its own internal CA. Step 3 shows that setup and the one line you remove to get a real Let’s Encrypt certificate instead. If you have not prepared the server yet, our Ubuntu 26.04 server setup checklist covers updates, SSH and the firewall first.
A few values repeat through the guide, so set them once in your shell. Pick your own passwords and keep the domain consistent with your DNS record:
export NTFY_DOMAIN="ntfy.example.com"
export ADMIN_PASS='Change-Me-Admin-1'
export PHONE_PASS='Change-Me-Phone-1'
export BOTS_PASS='Change-Me-Bots-1'
These variables only live in the current shell. If you log out between steps, export them again before you continue.
Step 1: Install Docker Engine and Compose
We install Docker from the upstream Docker apt repository because the Ubuntu docker.io package lags behind and ships without the Compose plugin we use. Docker already publishes a resolute suite for Ubuntu 26.04, and the command below reads the codename from /etc/os-release, so the same lines work on 24.04 (noble). Add the key and the repository first:
sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
Now write the repository definition in the deb822 format that current Ubuntu releases prefer:
echo "Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Signed-By: /etc/apt/keyrings/docker.asc" | sudo tee /etc/apt/sources.list.d/docker.sources
Install the engine and the Compose plugin, then add your user to the docker group so the rest of the guide runs without sudo. The newgrp line applies the group in the current shell; a fresh login does the same:
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo usermod -aG docker $USER
newgrp docker
Confirm both tools answer before going further, because a missing Compose plugin only shows up later as a confusing “unknown command” error.
docker --version
docker compose version
On our 26.04 VM both commands printed a version line, which means the engine and the plugin are in place.
Docker version 29.9.3, build 5457199
Docker Compose version v5.7.0
On our Ubuntu 24.04 VM the same commands wrote Suites: noble into the repository file and installed the identical Docker and Compose builds, so nothing in the rest of the guide changes between the two releases until borgmatic in Step 8.
Step 2: Write the ntfy Docker Compose file and server.yml
Everything for the server lives in one directory, which makes backups and moves to another host a single rsync. We pin the ntfy image to a release tag instead of latest, because ntfy releases often (three tags landed between 2 and 4 November 2026 alone) and an unplanned pull should never change the server under you. The tag goes into a .env file that Compose reads, filled from the GitHub releases API:
mkdir -p ~/ntfy/cache ~/ntfy/lib && cd ~/ntfy
echo "NTFY_TAG=$(curl -s https://api.github.com/repos/binwiederhier/ntfy/releases/latest | grep tag_name | cut -d '"' -f 4)" > .env
cat .env
The cat prints one NTFY_TAG= line with the newest release, and the tag keeps its leading v, which matches how the images are tagged on Docker Hub (a v2 tag, a minor-line tag and the full release). If the line comes back empty, the GitHub API rate limit is the usual cause; wait a few minutes or write the tag from the ntfy releases page by hand. To upgrade later, run the same echo line again and then docker compose up -d. Create the Compose file next:
vim ~/ntfy/compose.yaml
Paste the two services below. The healthcheck and init: true come from the ntfy install docs, and Caddy waits for ntfy to report healthy before it starts proxying:
services:
ntfy:
image: binwiederhier/ntfy:${NTFY_TAG}
container_name: ntfy
command: serve
volumes:
- ./server.yml:/etc/ntfy/server.yml:ro
- ./cache:/var/cache/ntfy
- ./lib:/var/lib/ntfy
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
caddy:
image: caddy:2
container_name: caddy
ports:
- "80:80"
- "443:443"
- "443:443/udp"
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro
- caddy_data:/data
- caddy_config:/config
depends_on:
ntfy:
condition: service_healthy
restart: unless-stopped
volumes:
caddy_data:
caddy_config:
Notice that the ntfy service has no ports: section. That is deliberate, because Docker publishes container ports straight through iptables and skips UFW rules, so a published 8080 would be open to the LAN even with UFW enabled. Keeping ntfy unpublished means the only way in is through Caddy. Now create the server config:
vim ~/ntfy/server.yml
This is the exact file our server ran with. It is short on purpose, because every line you leave out keeps its default and the defaults are sensible apart from access control.
base-url: "https://ntfy.example.com"
listen-http: ":80"
behind-proxy: true
cache-file: "/var/cache/ntfy/cache.db"
cache-duration: "12h"
attachment-cache-dir: "/var/cache/ntfy/attachments"
auth-file: "/var/lib/ntfy/user.db"
auth-default-access: "deny-all"
enable-login: true
Each line has a job, and three of them decide whether the server is private at all:
base-urlsets the public HTTPS address for links and the web appbehind-proxytrustsX-Forwarded-Forfrom Caddy for per-client rate limitscache-filekeeps messages for 12 hours so a phone that was offline catches upauth-fileholds users, ACLs and tokens in SQLiteauth-default-access: "deny-all"refuses anyone without a user or tokenenable-loginshows the sign-in page in the web app
The default for auth-default-access is read-write, which means a fresh ntfy server lets anybody who can reach it publish and read any topic. The ntfy configuration docs say to set deny-all for a private instance, and we agree: an open server with guessable topic names like backups is an invitation. Swap the example domain for yours in server.yml (and in the Caddyfile once you create it in the next step):
sed -i "s/ntfy.example.com/${NTFY_DOMAIN}/" ~/ntfy/server.yml
Nothing starts yet. Caddy needs its own config file before docker compose up makes sense, because the Compose file mounts it read-only into the Caddy container.
Step 3: Put ntfy behind Caddy for HTTPS
Caddy is the shortest path to HTTPS in front of ntfy because it obtains and renews certificates by itself and proxies WebSockets without extra directives, which the ntfy web app and the phone apps use for live delivery. Open the Caddyfile:
vim ~/ntfy/Caddyfile
Our lab file is three lines inside one site block. ntfy:80 is the Compose service name, so Caddy reaches ntfy over the internal network:
ntfy.example.com {
tls internal
reverse_proxy ntfy:80
}
The tls internal line tells Caddy to sign the certificate with its own local CA, which is what we needed on a private LAN with no public DNS. On a server with a public A record and ports 80 and 443 open, delete that line. Caddy then gets a Let’s Encrypt certificate through the HTTP-01 or TLS-ALPN challenge on first start, with no certbot and no cron job, as described in the Caddy automatic HTTPS docs. Set your domain in the file:
sed -i "s/ntfy.example.com/${NTFY_DOMAIN}/" ~/ntfy/Caddyfile
If UFW is active on the host, open the web ports. Docker would publish them anyway, but the rule documents your intent and covers the host if you later move Caddy out of Docker:
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp
Start the stack from the ~/ntfy directory. Compose waits for the ntfy healthcheck before it starts Caddy:
cd ~/ntfy
docker compose up -d
docker compose ps
Both containers are up and ntfy reports healthy. Only Caddy maps ports to the host, while ntfy shows a bare 80/tcp that exists only inside the Compose network:
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
caddy caddy:2 "caddy run --config …" caddy 11 seconds ago Up 5 seconds 0.0.0.0:80->80/tcp, [::]:80->80/tcp, 0.0.0.0:443->443/tcp, [::]:443->443/tcp, 0.0.0.0:443->443/udp, [::]:443->443/udp, 2019/tcp
ntfy binwiederhier/ntfy:v2.37.2 "ntfy serve" ntfy 12 seconds ago Up 10 seconds (healthy) 80/tcp
With tls internal, your clients do not trust the certificate yet. Copy the Caddy root CA out of the container and add it to the host trust store, which is also what curl, borgmatic and other system tools read. Skip this block if you use Let’s Encrypt:
docker compose cp caddy:/data/caddy/pki/authorities/local/root.crt ./caddy-root.crt
sudo cp caddy-root.crt /usr/local/share/ca-certificates/caddy-local-root.crt
sudo update-ca-certificates
Other machines that send to ntfy need the same file in their trust store. Our older guide on locally trusted certificates with mkcert covers the same idea for browsers. Check the version and the health endpoint over HTTPS:
docker compose exec ntfy ntfy --version
curl -s https://${NTFY_DOMAIN}/v1/health
A JSON healthy: true over a verified TLS connection proves the whole path works: DNS, Caddy, the certificate and the proxy hop into the container:
ntfy version 2.37.2
{"healthy":true,"role":"active"}
The terminal capture from ntfy01 shows the same check, with the IPv6 port entries trimmed from the docker compose ps view so it fits the window:

The server is reachable now, but nobody can use it yet, which is exactly what deny-all should do.
Step 4: Lock ntfy down with deny-all, users, ACLs and a token
Before adding anyone, prove the lock works. An anonymous publish should be refused with HTTP 403:
curl -s -d "hello from nobody" https://${NTFY_DOMAIN}/backups
ntfy answers with error code 40301, its forbidden response, and the message never reaches the cache:
{"code":40301,"http":403,"error":"forbidden","link":"https://ntfy.sh/docs/publish/#authentication"}
We split access into three accounts, because a token that only writes can leak from a script without exposing anything you read on your phone:
kibetis the admin and reads and writes every topicphonereadshomelab-*from the web app and phonebotswrites tohomelab-*and owns the sender token
The ntfy user add command prompts for a password, but it also reads NTFY_PASSWORD from the environment, which lets you script it. Create the three users (use your own admin name in place of kibet):
docker compose exec -e NTFY_PASSWORD="${ADMIN_PASS}" ntfy ntfy user add --role=admin kibet
docker compose exec -e NTFY_PASSWORD="${PHONE_PASS}" ntfy ntfy user add phone
docker compose exec -e NTFY_PASSWORD="${BOTS_PASS}" ntfy ntfy user add bots
Each command confirms the user and its role.
user kibet added with role admin
user phone added with role user
user bots added with role user
Grant the topic ACLs with a wildcard pattern, so every new homelab- topic is covered without another command. Quote the pattern so the shell does not expand the asterisk:
docker compose exec ntfy ntfy access phone "homelab-*" read-only
docker compose exec ntfy ntfy access bots "homelab-*" write-only
Then create a token for the bots user. A token is better than the bots password in scripts because you can revoke it on its own and its label shows what it is for:
docker compose exec ntfy ntfy token add --label="gatus-borgmatic" bots
Copy the tk_ value now. The token below is a placeholder in the same format as the one our server printed, and the rest of the guide uses it wherever your real token goes:
token tk_AgQdq7mVBoFD37zQVN29RhuMzNIz2 created for user bots, never expires
Running ntfy access with no arguments lists every rule, and it is the quickest audit you have:
docker compose exec ntfy ntfy access
Read the last block carefully. The anonymous user * has no topic rules, and the server config makes that a hard “no access”:
user kibet (role: admin, tier: none)
- read-write access to all topics (admin role)
user bots (role: user, tier: none)
- write-only access to topic homelab-*
user phone (role: user, tier: none)
- read-only access to topic homelab-*
user * (role: anonymous, tier: none)
- no topic-specific permissions
- no access to any (other) topics (server config)
Store the token in a root-only file on each machine that sends alerts, and export it for the curl tests that follow:
echo "tk_AgQdq7mVBoFD37zQVN29RhuMzNIz2" | sudo tee /etc/ntfy-token > /dev/null
sudo chmod 600 /etc/ntfy-token
export NTFY_TOKEN=$(sudo cat /etc/ntfy-token)
We tested the ACLs from both sides. The bots token can publish to homelab-uptime but gets 403 on a topic outside the pattern, and on reads of its own topics. The phone user gets 403 when it tries to publish and reads the same topic without trouble:

That split matters more than it looks. If a script on some forgotten VM leaks the token, the worst an attacker can do is send you fake alerts on homelab-* topics; they cannot read your backup history or touch any other topic.
Step 5: Send ntfy notifications with curl and an access token
Publishing is an HTTP POST to https://<server>/<topic> with the message as the body. Headers add the rest, and these four cover most homelab alerts:
Titlesets the bold first line of the notificationPrioritytakes 1 (min) to 5 (urgent), or names likehighTagstakes a comma list, and shortcodes likewarningbecome emojiClicksets the URL that opens when you tap the notification
Send a disk space warning with all four, authenticated with the bots token:
curl -s -H "Authorization: Bearer ${NTFY_TOKEN}" \
-H "Title: Disk space low on nas01" \
-H "Priority: high" \
-H "Tags: warning,floppy_disk" \
-H "Click: https://ntfy.example.com/homelab-uptime" \
-d "/srv/data is 91% full (182G of 200G)" \
https://${NTFY_DOMAIN}/homelab-uptime
ntfy echoes the stored message. Note that high became priority 4 and the expiry sits 12 hours after the send time, which is the cache-duration from server.yml:
{"id":"Wl3IFXFAKGG7","time":1794046856,"expires":1794090056,"event":"message","topic":"homelab-uptime","title":"Disk space low on nas01","message":"/srv/data is 91% full (182G of 200G)","priority":4,"tags":["warning","floppy_disk"],"click":"https://ntfy.example.com/homelab-uptime"}
Want to check what reached a topic without opening the app? A read-only user can poll it, which is handy inside scripts. With curl, -u user:password works too, and every other curl trick from our curl cheat sheet applies to these calls:
curl -s -u "phone:${PHONE_PASS}" "https://${NTFY_DOMAIN}/homelab-uptime/json?poll=1"
The poll returns one JSON line per cached message, here the disk warning we just sent. Polling is also a cheap way to test an ACL change, because a 403 here tells you the reader rule is wrong before you blame the phone app.
Step 6: Alert from a backup script
Most homelab jobs are a cron line that nobody watches, so the useful pattern is a wrapper: run any command, keep its output, and push the result with the exit code and the last log lines. A failure goes out as urgent, a success as low priority, so your phone only makes noise when something broke. Create the wrapper:
sudo vim /usr/local/bin/backup-notify.sh
Paste the script. Change NTFY_URL to your domain and topic:
#!/usr/bin/env bash
# Run a backup command and push the result to ntfy.
set -uo pipefail
NTFY_URL="https://ntfy.example.com/homelab-backups"
NTFY_TOKEN="$(cat /etc/ntfy-token)"
JOB="${1:?usage: backup-notify.sh <job-name> <command...>}"
shift
LOG="$(mktemp)"
START=$(date +%s)
"$@" >"$LOG" 2>&1
RC=$?
SECS=$(( $(date +%s) - START ))
if [ "$RC" -ne 0 ]; then
curl -s -o /dev/null -w "ntfy HTTP %{http_code}\n" \
-H "Authorization: Bearer ${NTFY_TOKEN}" \
-H "Title: Backup FAILED: ${JOB} on $(hostname)" \
-H "Priority: urgent" \
-H "Tags: rotating_light,${JOB}" \
--data-binary "Exit code ${RC} after ${SECS}s. Last lines:
$(tail -n 5 "$LOG")" \
"$NTFY_URL"
else
curl -s -o /dev/null -w "ntfy HTTP %{http_code}\n" \
-H "Authorization: Bearer ${NTFY_TOKEN}" \
-H "Title: Backup OK: ${JOB} on $(hostname)" \
-H "Priority: low" \
-H "Tags: white_check_mark,${JOB}" \
-d "Finished in ${SECS}s." \
"$NTFY_URL"
fi
rm -f "$LOG"
exit "$RC"
The script exits with the exit code of the wrapped command, so cron, systemd and anything else that chains on it still sees the failure. Make it executable and run one job that works and one that cannot, because /mnt/offsite and the PostgreSQL directory do not exist on this VM:
sudo chmod 755 /usr/local/bin/backup-notify.sh
sudo mkdir -p /srv/backups
sudo backup-notify.sh etc-tar tar -czf /srv/backups/etc.tar.gz /etc; echo "exit=$?"
sudo backup-notify.sh db-dump tar -czf /mnt/offsite/db.tar.gz /var/lib/postgresql; echo "exit=$?"
Both pushes were accepted with HTTP 200, and the second job kept the tar exit code 2.
ntfy HTTP 200
exit=0
ntfy HTTP 200
exit=2
The failure message carries the complaint from tar itself, so you know the cause before you open a terminal. This is what the admin user read back from the topic:
{"id":"BLeTnX8lrbiu","time":1794046874,"expires":1794090074,"event":"message","topic":"homelab-backups","title":"Backup FAILED: db-dump on ntfy01","message":"Exit code 2 after 0s. Last lines:\ntar: /var/lib/postgresql: Cannot stat: No such file or directory\nt
To use it from cron, put the wrapper in front of the real command, for example 30 2 * * * /usr/local/bin/backup-notify.sh restic-nas restic backup /srv/data.
Step 7: Send Gatus alerts to ntfy
Gatus has a native ntfy alerting provider, so the uptime checks from our Gatus monitoring guide can page your phone without a webhook shim. We ran Gatus in its own Compose project next to ntfy and pinned its tag the same way:
mkdir -p ~/gatus/config && cd ~/gatus
{ echo "GATUS_TAG=$(curl -s https://api.github.com/repos/TwiN/gatus/releases/latest | grep tag_name | cut -d '"' -f 4)"; echo "NTFY_TOKEN=${NTFY_TOKEN}"; } > .env
chmod 600 .env
vim compose.yaml
The token travels from .env into the container as an environment variable, and Gatus expands ${NTFY_TOKEN} inside its config, so the secret never sits in the YAML. The dashboard port is bound to 127.0.0.1 for the same reason ntfy has no published port: Gatus has no login, and a plain 8080:8080 would put it on the LAN past UFW. We checked it, and the dashboard answered 200 on the VM itself while another machine on the LAN could not connect. Reach it over an SSH tunnel, or put it behind Caddy with auth. The two extra_hosts lines only exist because our lab names are not in DNS; drop them when yours are:
services:
gatus:
image: twinproduction/gatus:${GATUS_TAG}
container_name: gatus
ports:
- "127.0.0.1:8080:8080"
environment:
NTFY_TOKEN: ${NTFY_TOKEN}
extra_hosts:
- "ntfy.example.com:host-gateway"
- "nas01.example.com:host-gateway"
volumes:
- ./config:/config:ro
- ../ntfy/caddy-root.crt:/etc/ssl/certs/caddy-root.crt:ro
restart: unless-stopped
Now the Gatus config with one alerting block and two endpoints. The ntfy endpoint watches the server itself; nas01-web is the check that carries the alert:
vim ~/gatus/config/config.yaml
Paste the config below. Two failures in a row trigger the alert, which filters out a single dropped request, and send-on-resolved tells you when the service comes back so you do not have to check.
alerting:
ntfy:
url: "https://ntfy.example.com"
topic: "homelab-uptime"
token: "${NTFY_TOKEN}"
priority: 4
click: "http://nas01.example.com:9999"
default-alert:
failure-threshold: 2
success-threshold: 1
send-on-resolved: true
endpoints:
- name: ntfy
group: core
url: "https://ntfy.example.com/v1/health"
interval: 30s
conditions:
- "[STATUS] == 200"
- "[BODY].healthy == true"
- name: nas01-web
group: storage
url: "http://nas01.example.com:9999/"
interval: 30s
conditions:
- "[STATUS] == 200"
alerts:
- type: ntfy
description: "nas01 web UI is not answering"
Our first run did not have the caddy-root.crt volume line, and that is the snag from the diagram. Gatus detected the outage on time, then failed to deliver every alert, because the Gatus image carries its own CA bundle and knows nothing about the internal CA in Caddy:
2026/11/07 10:22:14 [watchdog.handleAlertsToTrigger] Failed to send an alert for endpoint with key=storage_nas01-web: Post "https://ntfy.example.com": tls: failed to verify certificate: x509: certificate signed by unknown authority
The fix is the volume line you already pasted. Gatus is a Go binary, and Go on Linux loads every certificate file it finds in /etc/ssl/certs, so mounting the root CA there adds it without replacing the public CAs your other checks need. With a Let’s Encrypt certificate on ntfy, delete the caddy-root.crt volume line, because the file does not exist on your host and Docker would create an empty directory in its place. Start Gatus:
cd ~/gatus
docker compose up -d
docker compose logs --no-log-prefix | grep -E "handleAlerts"
With the CA mounted, the second failed check triggered the alert (that is the failure-threshold: 2), and starting a web server on port 9999 of nas01 a minute later produced the resolved message. The output is trimmed to one line per event, because Gatus logs each trigger twice (an “initial” line and a delivery line):
2026/11/07 10:23:46 [watchdog.handleAlertsToTrigger] Sending ntfy alert because alert for endpoint with key=storage_nas01-web with description='nas01 web UI is not answering' has been TRIGGERED
2026/11/07 10:24:46 [watchdog.handleAlertsToResolve] Sending ntfy alert because alert for endpoint with key=storage_nas01-web with description='nas01 web UI is not answering' has been RESOLVED
The terminal capture, trimmed the same way, shows the failed TLS attempt and the two deliveries that worked once the CA was mounted:

Gatus formats the title as Gatus: group/endpoint, adds a red siren for triggered and a green tick for resolved, and lists each failed condition with the value it saw. Here both alerts sit above the curl disk warning from Step 5 in the web app:

The [STATUS] (0) == 200 line in the triggered alert means Gatus got no HTTP response at all, which points at a dead service or a firewall rather than an application error.
Step 8: Send borgmatic backup pings to ntfy
borgmatic has a built-in ntfy hook that can fire on start, finish and failure. The hook syntax depends on the borgmatic version, and the two Ubuntu LTS releases ship very different ones, so check yours first. If you are new to borg, our BorgBackup with borgmatic guide covers repositories, encryption and retention in depth:
sudo apt-get install -y borgbackup borgmatic
borgmatic --version
borg --version
Ubuntu 26.04 installed borgmatic 2.0.11 with borg 1.4.4, new enough for everything below.
2.0.11
borg 1.4.4
Ubuntu 24.04 is a different story: it ships borgmatic 1.8.3 with borg 1.2.8, and token support in the ntfy hook only arrived in borgmatic 1.8.9. We pasted the same config on 24.04 and validation refused it:
At 'ntfy': Additional properties are not allowed ('access_token' was unexpected)
Configuration validation failed
On 24.04, replace the access_token line with username: bots and password: set to the bots password, and create the repository with sudo borgmatic rcreate --encryption repokey-blake2. The newer repo-create name crashed 1.8.3 with AttributeError: module 'logging' has no attribute 'DISABLED' in our run, while rcreate worked and the backup then logged Using basic auth with user bots for ntfy. Everything else in this step is the same on both releases.
Create the config file. It is root-only because it holds the repository passphrase and the token:
sudo mkdir -p /etc/borgmatic /srv/borg
sudo vim /etc/borgmatic/config.yaml
This is the file we ran on 26.04, with the lab token swapped for the placeholder. Each state gets its own priority, so the start ping is silent and only a failure rings at maximum:
source_directories:
- /etc
- /home
repositories:
- path: /srv/borg/homelab
label: local
encryption_passphrase: "Borg-Lab-Passphrase"
keep_daily: 7
keep_weekly: 4
ntfy:
topic: homelab-backups
server: https://ntfy.example.com
access_token: tk_AgQdq7mVBoFD37zQVN29RhuMzNIz2
start:
title: borgmatic started on ntfy01
message: Nightly backup is running
tags: borgmatic
priority: min
finish:
title: borgmatic finished on ntfy01
message: Backup and prune completed
tags: borgmatic,white_check_mark
priority: low
fail:
title: borgmatic FAILED on ntfy01
message: Check journalctl -u borgmatic for the error
tags: borgmatic,skull
priority: max
states:
- start
- finish
- fail
Without the states list, the hook only fires on fail, which is a sensible default if you do not want a ping every night. Replace the example passphrase with your own and keep a copy somewhere other than this host, because a repokey repository cannot be opened without it. Lock the file down, validate it and create the repository:
sudo chmod 600 /etc/borgmatic/config.yaml
sudo borgmatic config validate
sudo borgmatic repo-create --encryption repokey-blake2
Validation passes before anything touches the disk. repo-create then prints a reminder to export the borg key with borg key export and store it safely, and that advice is worth following before the first real backup.
summary:
All configuration files are valid
Run a backup by hand. borgmatic logs the moment it calls the hook:
sudo borgmatic --verbosity 1
The tail of the run shows the consistency check, the ntfy ping and a clean finish:
Archive consistency check complete, no problems found.
/etc/borgmatic/config.yaml: Pinging ntfy topic homelab-backups
summary:
/etc/borgmatic/config.yaml: Successfully ran configuration file
A success ping proves little, so we broke the backup on purpose by moving the repository away and running borgmatic again:
sudo mv /srv/borg/homelab /srv/borg/homelab.moved
sudo borgmatic --verbosity 1
sudo mv /srv/borg/homelab.moved /srv/borg/homelab
borg exits with status 13, borgmatic reports the error and exits 1, and the fail hook fires:
summary:
An error occurred
Error running actions for repository
Repository /srv/borg/homelab does not exist.
Command 'borg create --patterns-from /tmp/borgmatic-hl0xd34x/borgmatic/tmpq7tnu4zh --info /srv/borg/homelab::{hostname}-{now:%Y-%m-%dT%H:%M:%S.%f}' returned non-zero exit status 13.
Error running configuration
Here are both runs side by side in the terminal, the good one first.

In the web app the failure lands on top with the skull tag and the maximum priority marker, above the start and finish pings from the good run. The two backup script messages from Step 6 sit further down the same topic:

One detail worth copying: the failed run still sent its start ping. If you ever see a start with no finish or fail after it, borgmatic died hard (out of memory, a reboot) before its hooks could run, which is a signal on its own.
Step 9: Subscribe from the web app and your phone
The web app is served by ntfy itself at the base URL, and with enable-login it opens on a sign-in page. Use the read-only phone account here, not the admin, so a browser session left open somewhere cannot publish or manage users. Type the Username and Password, then click Sign in:

- 1Username
- 2Password
- 3Sign in
An empty sidebar greets you after the first login, because subscriptions are stored per browser. Click Subscribe to topic in the left menu:

Type homelab-uptime in the Topic name field and click Subscribe. Leave “Use another server” off, since the web app already points at your own server. Repeat for homelab-backups:

- 1Topic name
- 2Subscribe
The “Notifications are blocked” banner in our captures comes from the headless browser we used; in a normal browser, allow notifications when it asks and you get desktop pop-ups for new messages.
On Android, the ntfy app from Google Play or F-Droid can subscribe to topics on your own server URL and sign in with the same phone user. We did not have an Android phone on the lab LAN, so we did not capture that flow; the web app above is what we verified end to end.
iOS and upstream-base-url (from the docs, not tested on an iPhone)
iOS is the awkward one, and we could not test it because the lab has no iPhone. Everything in this subsection comes from the “iOS instant notifications” part of the ntfy config docs. Apple only allows instant background delivery through its push service, and the ntfy iOS app receives those pushes through ntfy.sh. Without help, the docs say messages from a self-hosted server “will still eventually get to your device, but delivery can take hours, depending on the state of the phone. If you are using your phone, it shouldn’t take more than 20-30 minutes though.” Both of those timings apply to a server without the relay.
The fix the docs give is one line in server.yml. With it, every incoming message makes your server publish a poll request to ntfy.sh, and the iPhone then fetches the actual message from your server:
upstream-base-url: "https://ntfy.sh"
The privacy cost is small but real. Per the docs, the request to ntfy.sh “contains only the message ID (in the X-Poll-ID header), and the SHA256 checksum of the topic URL”, so ntfy.sh never sees the message text or the topic name, but it does learn that your server sent something and when. There is also an optional upstream-access-token for when the upstream rate limits are exceeded or the upstream server needs auth. If any iPhone will subscribe, add the line; if every subscriber is Android or the web app, leave it out and nothing leaves your network.
Self-hosted ntfy vs ntfy.sh Pro vs Pushover: cost and limits
Is self-hosting worth it on cost alone? For one person, not really, and it is better to say that plainly. The table compares what each option charges and allows, using the ntfy.sh pricing page and its tier API plus the Pushover pricing page, all read on 7 November 2026:
| Option | Price | Message limit | Where messages live |
|---|---|---|---|
| Self-hosted ntfy (this guide) | $0 software; a VM you already run | Your own rate limits | Your server only |
| ntfy.sh free | $0 | 250 messages a day | ntfy.sh |
| ntfy.sh Supporter | $5 a month (listed as down from $6) | 2,500 a day, 3 reserved topics | ntfy.sh |
| ntfy.sh Pro | $10 a month (listed as down from $12) | 20,000 a day, 10 reserved topics | ntfy.sh |
| Pushover | $4.99 once per platform, 30-day trial | 10,000 a month per user | Pushover servers |
Pushover is the cheapest paid route by far: one $4.99 purchase for your phone platform covers years of alerts, and 10,000 messages a month is more than most homelabs send. ntfy.sh Supporter makes sense if you want reserved topic names and the ntfy apps without running anything. Self-hosting wins on control rather than money: no daily caps, no account, ACLs per topic and per token, and message bodies that never leave your network unless you turn on the iOS relay. It also costs almost nothing extra in resources, since our three containers used 32 MiB of RAM and the ntfy cache and user databases took 232 KB of disk after the whole lab:
NAME CPU % MEM USAGE / LIMIT
gatus 0.00% 6.801MiB / 3.819GiB
caddy 0.00% 11.68MiB / 3.819GiB
ntfy 0.07% 13.28MiB / 3.819GiB
The real cost is upkeep: patching the host, renewing trust when you move to new hardware, and watching the watcher. Point a second, external check at your ntfy health URL if alerts are critical, because a dead ntfy server fails silently. For a team or anyone with an iPhone-only household, Pushover or ntfy.sh is the less fragile choice.
What broke in the lab
These are the errors we actually hit or forced while building the server, with the cause and the fix for each.
Error: {“code”:40301,”http”:403,”error”:”forbidden”}
ntfy returns the same 403 for every permission problem, so work through the causes in order. With deny-all, any request without credentials gets it. A token that is valid but owned by a user without a matching ACL gets it too: our bots token was refused on random-topic and on reads of homelab-uptime, because its rule only allows writes to homelab-*. Run docker compose exec ntfy ntfy access and compare the topic and the direction (read or write) with what the client is doing.
Error: {“code”:42901,”http”:429,”error”:”limit reached: too many requests”}
ntfy rate limits each visitor with a bucket of 60 requests that refills at one request every 5 seconds. Behind a proxy without behind-proxy: true, every client looks like the Caddy container IP, so all of them share one bucket. We proved it by setting behind-proxy: false, sending 65 messages from ntfy01 and then one message from a different machine on the LAN:
60 200
5 429
=== second client (other machine)
{"code":42901,"http":429,"error":"limit reached: too many requests","link":"https://ntfy.sh/docs/publish/#limitations"}
The other machine had sent nothing, yet the burst from ntfy01 had used up its bucket too. With behind-proxy: true restored and the same burst repeated, ntfy01 still hit its own limit after 60 requests, but the message from the second machine went straight through because ntfy now reads the real client address from X-Forwarded-For. If one noisy script keeps tripping the limit on its own, raise visitor-request-limit-burst in server.yml rather than turning off the proxy setting.
Error: x509: certificate signed by unknown authority
Any sender that does not trust your certificate fails here, and the alert is lost while the monitor keeps reporting the outage correctly, which makes it easy to miss. Gatus hit it in Step 7 because its container ships its own CA bundle. With the Caddy internal CA, add root.crt to the trust store of every sender (or mount it into /etc/ssl/certs for Go containers); with a Let’s Encrypt certificate, the error does not occur. Our wg-easy Docker guide uses the same one-host Compose pattern if you want to reach this server privately over WireGuard instead of exposing it, and the server closet cooling build shows another sender in action, pushing temperature alerts to ntfy.