Ntfy

ntfy is a HTTP-based pub-sub notification service. It allows sending notifications to a phone or desktop via scripts from any computer, and/or using a REST API. It can be used for free, with a paid plan or self-hosted. The latter is documented in this article.

Installation

Enable the ntfy module in your configuration and define some basic options:

services.ntfy-sh = {
    enable = true;
    settings = {
      base-url = "https://ntfy.yourdomain.com";
      behind-proxy = true;
      };
    };

You also should set up a virtual host via nginx or caddy:

services.nginx.virtualHosts = {
    "ntfy.yourdomain.com" = {
      forceSSL = true;
      enableACME = true;
      locations."/" = {
        proxyPass = "http://localhost:2586";
        proxyWebsockets = true;  # Required for ntfy streaming
        };
      };
    };

If you haven't done so for other services, you will also need an ACME setup. A minimal working example:

security.ACME = {
    acceptTerms = true;
    defaults.email = <youremail>;
    };

Also note that you might need to restart the ACME service after first setup due to a bug:

sudo systemctl restart acme-ntfy.yourdomain.com.service

Authentication (optional but recommended)

For a private instance you should restrict access. Set up a user database and default to denying all access:

services.ntfy-sh.settings = {
  auth-file = "/var/lib/ntfy-sh/user.db";
  auth-default-access = "deny-all";
  enable-signup = false;
};

Define users and access tokens (tokens can be generated with ntfy token generate).

services.ntfy-sh.settings = {
  auth-users = [
    # <username>:<password-hash>:<role>   role is "user" or "admin"
    "admin:$2a$10$<bcrypt-hash>:admin"
    "backup-service:$2a$10$<bcrypt-hash>:user"
  ];
  auth-tokens = [
    # <username>:<token>[:<optional free form label>]
    "admin:tk_<token>"
    "backup-service:tk_<token>:backup script token"
  ];
};

Define an access control list (ACL). The format is username:topic-pattern:access, where access is read-write/rw, read-only/ro, write-only/wo or deny-all. The wildcard * matches any number of characters in a topic pattern, and the special user * means "everyone" (including anonymous):

services.ntfy-sh.settings = {
  auth-access = [
    "user:*:rw"        # you can read & write everything
    "backup-service:backups:*:rw"   # only its own topics
  ];
};

After a nixos-rebuild switch, the user.db is created automatically and the users/tokens/ACL entries are applied.

If your ntfy instance is private (auth-default-access = "deny-all"), and you want to use it as a UnifiedPush push server (e.g. for MollySocket or Matrix/fediverse push), you must explicitly allow anonymous write access to the up* topic prefix as application servers such as mollysocket are not registered users and cannot authenticate:

services.ntfy-sh.settings = {
  auth-access = [
    "*:up*:write-only"    # anonymous app-servers may publish to UnifiedPush topics
  ];
};

Use

Publishing

Publishing is done via HTTP PUT/POST or the ntfy CLI. Topics are created on the fly by publishing or subscribing to them, so for basic use no configuration is needed at all. Because there is no sign-up, a topic name is essentially a password. That's why you should pick something not easily guessable:

# Simple message (default priority)
curl -d "Backup finished" https://ntfy.yourdomain.com/mytopic

# With title, priority and tags
curl -H "Title: Backup" -H "Priority: high" -H "Tags: warning" \
     -d "Backup of server failed" https://ntfy.yourdomain.com/backups

# From a script
ntfy publish mytopic "Something has happened"

If access control is enabled and the topic does not allow anonymous writes, authenticate with a token (ntfy://:TOKEN@DOMAIN/TOPIC or Authorization: Bearer):

curl -H "Authorization: Bearer tk_..." -d "Backup finished" \
     https://ntfy.yourdomain.com/backups

Subscribing

Subscribe via the web app (ntfy.sh/app on your own instance), the mobile app, or the API. The subscription API supports plain HTTP streams (JSON, SSE or raw) and WebSockets:

# Stream as JSON lines
curl -s https://ntfy.yourdomain.com/mytopic/json

# Server-sent events
curl -s https://ntfy.yourdomain.com/mytopic/sse

# WebSocket (wss://)
wscat -c wss://ntfy.yourdomain.com/mytopic/ws

Android (Play Store + F-Droid) and iOS apps are available, too. On Android, the app can also act as a UnifiedPush distributor, forwarding pushes to other apps (e.g. Molly/MollySocket). On NixOS, the ntfy package can be used to subscribe to topics and receive notifications on your desktop.

References

Full documentation: ntfy docs, configuration, publishing.