Containers

Self-Host ntfy with Docker Compose: HTTPS, Auth and Alerts

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.

Original content from computingforgeeks.com - post 185585

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.

Self-hosted ntfy architecture diagram: phone, Gatus and borgmatic reach Caddy on HTTPS 443, Caddy proxies to ntfy on port 80 inside Docker Compose

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-url sets the public HTTPS address for links and the web app
  • behind-proxy trusts X-Forwarded-For from Caddy for per-client rate limits
  • cache-file keeps messages for 12 hours so a phone that was offline catches up
  • auth-file holds users, ACLs and tokens in SQLite
  • auth-default-access: "deny-all" refuses anyone without a user or token
  • enable-login shows 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:

ntfy docker compose ps showing ntfy healthy and Caddy publishing 80 and 443, ntfy version and health check over HTTPS on Ubuntu 26.04

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:

  • kibet is the admin and reads and writes every topic
  • phone reads homelab-* from the web app and phone
  • bots writes to homelab-* 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:

ntfy deny-all returning 403 forbidden to an anonymous publish, a bots access token publishing to homelab-uptime and 403 on another topic

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:

  • Title sets the bold first line of the notification
  • Priority takes 1 (min) to 5 (urgent), or names like high
  • Tags takes a comma list, and shortcodes like warning become emoji
  • Click sets 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 logs showing an x509 unknown authority failure, then ntfy alerts sent for TRIGGERED and RESOLVED states

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:

ntfy web app showing Gatus triggered and resolved alerts plus a curl disk space warning on the homelab-uptime topic

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.

borgmatic run pinging the ntfy topic homelab-backups, then a failed run with Repository does not exist on Ubuntu 26.04

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:

ntfy web app showing borgmatic FAILED, started and finished notifications on the homelab-backups 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:

ntfy web app sign-in page on a self-hosted server with the username, password and Sign in controls marked
  1. 1Username
  2. 2Password
  3. 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:

ntfy web app after sign-in with the Subscribe to topic entry in the sidebar marked

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:

ntfy Subscribe to topic dialog with homelab-uptime typed in the topic name field and the Subscribe button marked
  1. 1Topic name
  2. 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:

OptionPriceMessage limitWhere messages live
Self-hosted ntfy (this guide)$0 software; a VM you already runYour own rate limitsYour server only
ntfy.sh free$0250 messages a dayntfy.sh
ntfy.sh Supporter$5 a month (listed as down from $6)2,500 a day, 3 reserved topicsntfy.sh
ntfy.sh Pro$10 a month (listed as down from $12)20,000 a day, 10 reserved topicsntfy.sh
Pushover$4.99 once per platform, 30-day trial10,000 a month per userPushover 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.

Keep reading

Best UI Applications for Managing Docker Containers Containers Best UI Applications for Managing Docker Containers Install Docker and Run Containers on Ubuntu 24.04|22.04 Containers Install Docker and Run Containers on Ubuntu 24.04|22.04 Install Wazuh SIEM on Ubuntu 26.04 LTS: All-in-One Setup Monitoring Install Wazuh SIEM on Ubuntu 26.04 LTS: All-in-One Setup OpenCloud vs ownCloud vs Nextcloud: Tested on Identical VMs Cloud OpenCloud vs ownCloud vs Nextcloud: Tested on Identical VMs Kiri Container Runtime on Linux: Install and Benchmark vs Docker Containers Kiri Container Runtime on Linux: Install and Benchmark vs Docker Deploy HA Kubernetes Cluster on Rocky Linux 10 Using Kubespray AlmaLinux Deploy HA Kubernetes Cluster on Rocky Linux 10 Using Kubespray

Leave a Comment

Press ESC to close