Technical

NTFY, not a typo, awesome tool for push notifications.

Darth Seldon

Oct 27, 2024 • 3 min read

This is going to be a short post.

NTFY, is a tool to send push notifications, specially to mobile.

Why would you like to use this tool?

Use cases that I can think of but not limited are

Check if a site is down
A long running task is done
A task has been assigned
Warning on a test
Unit tests failed or completed
And many more...

It is free and it is convenient. You saw that on a previous post

https://darthseldon.net/publishing-nuget-packages-with-github-actions/

How after a long running process I can send myself a notification if the NuGet packages were published correctly or not.

We will be installing the tool in docker and using the Nginx reverse proxy.

docker run -v /var/cache/ntfy:/var/cache/ntfy -v /etc/ntfy:/etc/ntfy -p 8070:80 --network=host -itd binwiederhier/ntfy serve --cache-file /var/cache/ntfy/cache.db

The command

Uses caches and will use a local volume
Uses the cache.db for local caching
Mounts the etc/ntfy folder for configuration
Uses the port 8070
Uses the image binwiederhier/ntfy with the flags itd

Now we need the configuration, since we will be serving the service thru a proxy and we want to enable IOS notifications as well, the following configuration is necessary.

Create a file named server.yml at the etc/ntfy folder.

base-url: "https://yourserver/ntfytool"
listen-http: "127.0.0.1:8070"
behind-proxy: true
keepalive-interval: "45s"
upstream-base-url: "https://ntfy.sh"

base-url will be your server and the virtual directory
listen-http will be the localhost with the port the tool is executing (in this case 8070)
behind-proxy well it is kind of obvious
upstream-base-url is the line of code that allows us to send notification to IOS

That last line will enable mostly real time notifications in IOS. From the documentation of NTFY

"Unlike Android, iOS heavily restricts background processing, which sadly makes it impossible to implement instant push notifications without a central server.

To still support instant notifications on iOS through your self-hosted ntfy server, you have to forward so called poll_request messages to the main ntfy.sh server (or any upstream server that's APNS/Firebase connected, if you build your own iOS app), which will then forward it to Firebase/APNS."

Lastly, we will add the virtual directory to Nginx

location /ntfytool/ {
        proxy_pass http://127.0.0.1:8070/;
        proxy_http_version 1.1;
        proxy_buffering off;
        proxy_read_timeout    90;
        proxy_connect_timeout 90;
        proxy_redirect        off;
        proxy_set_header Host $host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Port 443;
        proxy_set_header Proxy "";
    }

That's it, you have your notification server up and running. To send notifications you will need to do a post to the URL and a channel name.

https://yourserver/ntfytool/mytest