What are we building?

By the end, ntfy 2.26 runs in Docker behind your Traefik reverse proxy, reachable under your own (sub)domain with HTTPS. You can then send a push message from any script, cron job or monitoring tool – with a simple HTTP request – and get it displayed instantly in the ntfy app on your phone or in the browser, including title, priority, emojis and optional actions.

The clever part: ntfy is extremely lightweight (runs easily on the smallest VPS) and the data stays with you. We set the server up private right away – only with credentials may someone send or read messages.

Why ntfy and not a ready-made service like Pushover or a Telegram bot? Because here you need no account with third parties, hand no message contents to foreign servers, and the interface is as simple as it gets: anything that can fire an HTTP request – a shell script, a cron job, a monitoring tool – can notify you, without any SDK or API library. Exactly this reduction to “POST to a URL” makes ntfy so easy to connect to a self-hosted setup.

Prerequisites

• A hardened server with Debian 13 and Docker
• A running Traefik reverse proxy with the external network proxy and the resolver le
• A (sub)domain whose A/AAAA record points to your server, e.g. ntfy.YOUR_DOMAIN
• Optional but recommended: the ntfy app (Android/F-Droid/iOS) to really get push on your phone

ntfy is so frugal that it runs without problems alongside many other services on a VPS 1000 – the server calculator shows you how little it needs.

Step by step

Step 1: Write the compose.yaml

Create the project folder:

mkdir -p /opt/ntfy && cd /opt/ntfy

Create /opt/ntfy/compose.yaml. Replace ntfy.YOUR_DOMAIN with your real (sub)domain – it appears both in the NTFY_BASE_URL and in the Traefik label:

services:
  ntfy:
    image: binwiederhier/ntfy:v2.26
    container_name: ntfy
    command: serve
    environment:
      NTFY_BASE_URL: https://ntfy.YOUR_DOMAIN
      NTFY_LISTEN_HTTP: ":80"
      NTFY_BEHIND_PROXY: "true"
      NTFY_ENABLE_LOGIN: "true"
      NTFY_REQUIRE_LOGIN: "true"
      NTFY_CACHE_FILE: /var/lib/ntfy/cache.db
      NTFY_AUTH_FILE: /var/lib/ntfy/auth.db
      NTFY_AUTH_DEFAULT_ACCESS: "deny-all"
      NTFY_ATTACHMENT_CACHE_DIR: /var/lib/ntfy/attachments
    volumes:
      - data:/var/lib/ntfy
    networks: [proxy]
    restart: unless-stopped
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.ntfy.rule=Host(`ntfy.YOUR_DOMAIN`)"
      - "traefik.http.routers.ntfy.entrypoints=websecure"
      - "traefik.http.routers.ntfy.tls.certresolver=le"
      - "traefik.http.services.ntfy.loadbalancer.server.port=80"

networks:
  proxy:
    external: true

volumes:
  data:

The most important lines:

• NTFY_BASE_URL must be exactly your public HTTPS address – otherwise the app and the web client refuse the connection.
• NTFY_BEHIND_PROXY: "true" tells ntfy it runs behind Traefik, so it reads the real visitor IP from the proxy headers (important for rate limiting).
• NTFY_AUTH_DEFAULT_ACCESS: "deny-all" is the security screw: by default nobody may read or write. Access is only granted to whoever we explicitly create in a moment. Without this line your server would be an open push relay for the whole world.
• NTFY_ENABLE_LOGIN / NTFY_REQUIRE_LOGIN enable the login in the web client and make it mandatory. With NTFY_REQUIRE_LOGIN, an unauthenticated visitor gets a login screen directly instead of an empty interface.

Step 2: Start the server

docker compose up -d

Check that the container is running:

docker compose ps

NAME   IMAGE                       COMMAND         SERVICE   STATUS
ntfy   binwiederhier/ntfy:v2.26    "ntfy serve"    ntfy      Up 4 seconds

(For readability, the columns CREATED and PORTS are hidden here.)

Traefik fetches a certificate automatically. Check the health endpoint from your machine:

curl -s https://ntfy.YOUR_DOMAIN/v1/health

{"healthy":true}

If the server responds with {"healthy":true}, the chain of DNS, Traefik, TLS and ntfy is in place.

Step 3: Create a user

Because we set deny-all, you need at least one user. Create an administrator (they may write to and read all topics):

docker exec -it ntfy ntfy user add --role=admin admin

ntfy asks twice for a password and then confirms:

user admin added with role admin

Check the result:

docker exec ntfy ntfy user list

user admin (role: admin, tier: none)
- read-write access to all topics (admin role)

Step 4: Subscribe to a topic

In ntfy everything runs via topics – freely chosen names under which messages run. Open https://ntfy.YOUR_DOMAIN in the browser. Thanks to NTFY_REQUIRE_LOGIN, the web client greets you directly with a login screen – log in there with your created admin account (without login, deny-all blocks every read and subscribe attempt with HTTP 403). Then click Subscribe to topic on the left and choose a hard-to-guess name (e.g. serverkueche-alerts):

On the phone you set up your own server once in the ntfy app: open Settings → Default server and enter https://ntfy.YOUR_DOMAIN. Then store your credentials for this server under User management. Now you can add a topic just like in the browser – the app no longer asks about the big ntfy.sh server, but uses yours. From now on every message to this topic lands as a real push notification on the device, even with the app closed. On iOS the reception runs via Apple’s push service; the app explains at first launch what’s needed once for that.

Step 5: Send a message

Now the actual purpose – send a message via curl. Because the server is private, you supply your credentials (-u USER:PASSWORD):

curl -u admin:YOUR_PASSWORD -d "Backup completed successfully" https://ntfy.YOUR_DOMAIN/serverkueche-alerts

That’s it – the message is instantly on all subscribed devices. With a few additional headers it becomes more meaningful: title, priority (1–5) and tags (which also appear as emojis):

curl -u admin:YOUR_PASSWORD \
  -H "Title: Monitoring warning" \
  -H "Priority: 4" \
  -H "Tags: warning" \
  -d "High CPU load on the VPS" \
  https://ntfy.YOUR_DOMAIN/serverkueche-alerts

The priority controls how intrusive the message arrives: 5 (max) makes the phone ring and vibrate, 4 (high) reports clearly, 3 is the default, 2 and 1 (low/min) land quietly in the list. For “server unreachable” you use 5, for “backup ok” rather 2 – this way you don’t become numb to the important alarms.

Tags turn into emojis if they match a known name: warning → ⚠️, white_check_mark → ✅, rotating_light → 🚨. Multiple tags you give comma-separated (-H "Tags: rotating_light,skull"). And with the Click header, a tap on the message opens a URL directly – handy to jump straight from the alarm into the dashboard:

curl -u admin:YOUR_PASSWORD \
  -H "Title: Uptime Kuma: service down" \
  -H "Priority: 5" \
  -H "Tags: rotating_light" \
  -H "Click: https://status.YOUR_DOMAIN" \
  -d "Nextcloud is not responding" \
  https://ntfy.YOUR_DOMAIN/serverkueche-alerts

It gets really powerful with action buttons: via the Actions header you show buttons right in the notification that open a URL or trigger an HTTP request – so you acknowledge an alarm with a fingertip, without even opening the app:

curl -u admin:YOUR_PASSWORD \
  -H "Title: Restart server?" \
  -H "Actions: view, Open status, https://status.YOUR_DOMAIN" \
  -d "A service is stuck – check the status board." \
  https://ntfy.YOUR_DOMAIN/serverkueche-alerts

You can also comfortably click the same message together via the web client – handy for trying out all the options:

Step 6: Messages arrive

In the web client (provided you’re logged in there with your admin account as in step 4) and in parallel in the app, the messages appear immediately – with title, timestamp and color-highlighted priority:

By the way, you can install the web client in Chrome or Edge as an app (PWA): then you also get push notifications on the desktop without having to keep a tab open – handy when the computer is running anyway and you want to see alarms directly on screen.

Step 7: Access tokens for scripts instead of a password

Storing a password in every cron job and backup script is ugly. Better is an access token that you can revoke individually at any time:

docker exec ntfy ntfy token add admin

ntfy returns a token that starts with tk_. You then use it instead of -u as a bearer token:

curl -H "Authorization: Bearer tk_YOUR_TOKEN" \
  -H "Title: Nightly backup" \
  -d "Restic backup ran without errors" \
  https://ntfy.YOUR_DOMAIN/serverkueche-alerts

This way you can cleanly build ntfy into your Restic backups (a message at the end of the backup script) or have Uptime Kuma use it as a notification channel – Uptime Kuma knows ntfy as a built-in notification type.

Step 8: Practical example – a backup script that reports in

ntfy becomes most useful when a script automatically reports in. The following pattern wraps an arbitrary command and sends, depending on the outcome, a quiet success or a loud failure message. Save it as /opt/scripts/backup-notify.sh and adjust the domain, token and the actual backup command:

#!/usr/bin/env bash
set -uo pipefail

NTFY_URL="https://ntfy.YOUR_DOMAIN/serverkueche-alerts"
NTFY_TOKEN="tk_YOUR_TOKEN"

# Your actual backup command goes here – the exit code decides the message:
if restic backup /opt --tag nightly; then
  curl -s -H "Authorization: Bearer $NTFY_TOKEN" \
    -H "Title: Backup ok" -H "Tags: white_check_mark" -H "Priority: 2" \
    -d "Nightly backup ran without errors." "$NTFY_URL"
else
  curl -s -H "Authorization: Bearer $NTFY_TOKEN" \
    -H "Title: BACKUP FAILED" -H "Tags: rotating_light" -H "Priority: 5" \
    -d "The backup aborted with an error – please check immediately." "$NTFY_URL"
fi

Make it executable and test it once by hand:

chmod +x /opt/scripts/backup-notify.sh
/opt/scripts/backup-notify.sh

If it runs cleanly, you hang it in a cron job – this way you get a short confirmation every night and are woken with full priority on an error:

crontab -e

30 3 * * * /opt/scripts/backup-notify.sh

The principle transfers to anything: a certificate expires, a disk fills up (check df in the script), a deployment is done. Always the same one-liner – a curl to your topic. Exactly this makes ntfy so practical: you don’t have to integrate anything, and anything that can do HTTP can notify you.

When things go wrong

Maintenance & backups

Updates you pull within the pinned version like this:

cd /opt/ntfy && docker compose pull && docker compose up -d

For a jump to a new major version, read the release notes first and raise the image tag.

Backups: ntfy stores users, access rights and the message cache in its SQLite files in the volume (cache.db, auth.db). Back up the contents regularly by packing the volume into an archive …

docker run --rm -v ntfy_data:/data -v /opt/backups:/backup alpine:3 \
  tar czf /backup/ntfy-data.tar.gz -C /data .

… and include this archive in your encrypted off-site backup with Restic. The message cache is dispensable (push messages are ephemeral), but you don’t want to rebuild the user and rights database after a failure.

In everyday use ntfy is nearly maintenance-free. Occasionally check with docker exec ntfy ntfy user list who has access, and revoke no-longer-used tokens with ntfy token remove USER TOKEN-ID (the IDs are shown by ntfy token list USER) – this way your push server stays your own.