Ntfy — Self-hosted push notification server for all your services

Introduction

In our journey of self-hosting various services, one common need that often arises is the ability to receive notifications.

Initially, I started with sending out these notifications to a Discord private server, but I wanted to move out of Discord and into a self-hosted solution. That’s when I discovered Ntfy ↗️.

Whether it’s alerts from my monitoring system, updates from my download queue, or notifications about system events, having a reliable way to get these messages is crucial. This is where Ntfy comes in – a simple, lightweight, and powerful notification service that you can self-host.

What is Ntfy?

Ntfy ↗️ (pronounced “notify”) is an open-source pub-sub notification service that allows you to send notifications to your phone or desktop using simple HTTP PUT/POST requests. It’s designed to be simple to use yet powerful enough to handle complex notification scenarios.

Key features include:

• Send notifications via simple HTTP requests.
• Mobile apps for Android and iOS.
• Web app for desktop notifications.
• Attachments support (files, images, etc.)
• Priority levels and notification categories.
• First party command line interface (CLI).
• Access control and authentication.
• Simple API that works with curl, wget, or any HTTP client.

Setup Ntfy

The easiest way to set up Ntfy is using Docker. However if you want to run it natively, you can download the binary from the official website ↗️.

Since I’m using Docker, I’ll share on how to set it up using Docker. Create a new directory for Ntfy and create a docker-compose.yml file with the following content:

services:
  ntfy:
    image: binwiederhier/ntfy:latest
    container_name: ntfy
    command:
      - serve
    environment:
      - TZ=Asia/Kolkata
    user: '1000:1000'
    volumes:
      - ./cache:/var/cache/ntfy
      - ./config:/etc/ntfy
    ports:
      - '8082: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
    restart: unless-stopped

If you want, you can configure Ntfy to use a custom domain and enable authentication by adding a server.yml file in the config directory:

base-url: 'https://ntfy.yourdomain.com'
behind-proxy: true
auth-file: '/var/lib/ntfy/user.db'
auth-default-access: 'deny-all'
enable-signup: false

This is more for security and privacy reasons, if you are running Ntfy on a public server its better to disable signup and enable authentication so that only you can send notifications to your server and not random people.

Read more about the configuration options in the official documentation ↗️.

With that done, create the necessary directories:

mkdir -p config cache

And start the container:

docker compose up -d

Setting Up Authentication

For security, let’s create a user account:

docker exec -it ntfy ntfy user add --role=admin <yourusername>

You’ll be prompted to enter a password. Remember these credentials as you’ll need them to access the web UI and send notifications.

Again, you can skip this step if you are running Ntfy in your private homelab and don’t want to enable authentication. (No harm in doing it though)

Using Ntfy

Sending Notifications

The simplest way to send a notification is using curl:

curl -u "yourusername:yourpassword" -d "Hello from Ntfy!" https://ntfy.yourdomain.com/mytopic

You can also send more complex notifications with priorities, titles, and tags:

curl -u "yourusername:yourpassword" \
  -H "Title: Backup Complete" \
  -H "Priority: high" \
  -H "Tags: white_check_mark" \
  -d "Daily backup completed successfully!" \
  https://ntfy.yourdomain.com/backup-alerts

Receiving Notifications

1. Install the Ntfy app on your phone (Android ↗️ / iOS ↗️)
2. Add your Ntfy server (https://ntfy.yourdomain.com ↗️)
3. Enter your credentials
4. Subscribe to topics you want to receive notifications from

You can also use the web interface at https://ntfy.yourdomain.com ↗️ to manage subscriptions and view notifications.

How I am using Ntfy

Here are some practical examples of how I am using Ntfy in my homelab:

System Monitoring

if [ $(df -h / | awk 'NR==2 {print $5}' | sed 's/%//') -gt 90 ]; then
  curl -u "user:pass" -H "Title: Disk Space Alert" -H "Priority: high" \
    -d "Root partition is running low on space!" https://ntfy.mydomain.com/system-alerts
fi

if [ $(free | awk '/^Mem:/{print $7/$2*100}' | awk '{print int($1)}') -lt 10 ]; then
  curl -u "user:pass" -H "Title: Low Memory Alert" -H "Priority: high" \
    -d "Available memory is running low!" https://ntfy.mydomain.com/system-alerts
fi

This is a simple script that checks the disk space of the root partition and the available memory (RAM) and if they are running low, it sends a notification via Ntfy.

Package Updates

sudo apt-get update >> /dev/null
packages=$(apt list --upgradable 2>/dev/null | grep -v "Listing...")
if [ -n "$packages" ]; then
    curl -u "user:pass" \
        -H "Title: Package Updates Available" \
        -H "Priority: high" \
        -H "Tags: package" \
        -d "The following packages can be upgraded:\n\n$packages" \
        https://ntfy.mydomain.com/system-updates
fi

Another simple script to check for updates and send a notification if there are any updates available.

Backup Completion Notification

Majorly every service that I have, which have some dependency on a database or datastore/config in general, I usually have a backup script for it which automatically runs at a specific interval.

Once the backup is finished, I send out a notification to my phone to let me know that the backup has been completed successfully. This one is usually of a lower priority so that it doesn’t clutter my notifications.

backup_script.sh && \
curl -u "user:pass" -H "Title: Backup Status" -H "Tags: white_check_mark" -H "Priority: min" \
-d "Backup completed successfully!" https://ntfy.mydomain.com/backup-status

And for the failed backups, I send a notification with a higher priority so that I can immediately look into it.

💡

Friendly Advice

One thing to remember when setting up alerts (and this is a general advice and not specific to Ntfy) is that you should not spam yourself with notifications. So if you are setting up alerts for a service, try to set it up in a way that it doesn’t send out a notification every time the service is checked (or even if it does, make sure it’s a low priority notification so you don’t get spammed).

More often than not, you don’t need to be notified every time the service is checked, you just need to be notified when there is an issue.

Conclusion

Ntfy is an invaluable tool in any self-hosted setup, providing a reliable and simple way to implement notifications across your services.

I’ve been using Ntfy for several months now, and it has become an essential part of my homelab monitoring setup. The ability to receive instant notifications about important events has made managing my self-hosted services much more efficient.

Have you implemented Ntfy in your homelab? Do you use some other service for push notifications? Share your experiences in the comments below, or reach out to me on Twitter ↗️ / Reddit ↗️.

Happy notifying!