When looking for information on how to use NTFY with Home Assistant I was unable to find anything, esp around the security element of an open (by default) messaging tool.
But I figured out the basics and a little more and thought I’d share a step-by-step method here to help bump start someone else’s journey that may be looking to do the same.
How it works:
NTFY follows the same idea as MQ(TT) where there are “topics” created and users subscribe to that topic to receive and/or send messages.
When content is added to a topic then all subscribers/devices of that topic receive a copy locally.
Messages are cached for a time and delivered as soon as connected.
Plan:
Set up two channels of notifications. One for general info and one for important info
Maybe one extra for family chitchat.
Pre-requisites
- A method of self hosting NTFY
- A method of sharing it externally using a domain
1 In our setup, the self-hosting method is Docker on a *nix system.
2 We use Nginx Proxy Manager (NPM) in docker for external access.
2b Alternatively you could use a Cloudflare Tunnel to do this.
.
Step 1: Prep
This is a typical directory structure for docker:
~/scripts/ - to hold the scripted docker launcher.
/opt/docker/[application] - docker mounted volumes for persistent data.
To create the folders you need to host NTFY, SSH into your host and:
mkdir /opt/docker/ntfy/cache
.
Step 2: Install
Ceate your Docker CLI script to create the container + add it to a shared docker network (v. useful if you’ll be using a Cloudflared tunnel). In this instance, “localproxy” has an IP range of 172.29.0.*
File: ~/scripts/ntfy
docker stop ntfy
docker rm ntfy
sleep 1
docker pull binwiederhier/ntfy
echo Starting ntfy
docker run -d \
--name ntfy \
-h ntfy \
--network=localproxy \
--ip 172.29.0.50 \
-p 8000:80 \
-e PUID=1000\
-e PGID=100 \
-e TZ=Europe/London \
-v /opt/docker/ntfy:/etc/ntfy \
-v /opt/docker/ntfy/cache:/var/cache/ntfy \
--restart=unless-stopped \
binwiederhier/ntfy \
serve
To make the script executeable:
chmod 755 ~/scripts/ntfy
( or to get a Docker-Compose equivalent, run the above CLI through https://www.composerize.com/)
Once it’s running you should be able to see it with the command:
docker stats ntfy
Now it’s running, you should be able to connect to your instance’ UI using a web browser: http://[DockerHost]:8000
.
Step 3: Setup External access
To access it externally, either add it to a ProxyManager or CloudFlare Tunnel.
Our NPM uses the same shared docker network “localproxy” so it can use appname:80 in the destination as seen below.
Otherwise we’d have to configure the destination using the defined docker network IP 172.29.0.50:8000
If configuring with Cloudflared tunnels, specifying the 172.29.0.50 IP in the docker CLI as we did should make it easier to configure.
.
Step 4: Lock it down
Right now it’s up and running, but there’s no users and therefore no security.
Anyone can connect and create a “topic” and start sending messages.
To lock it down we set to create the parameter file to tell NTFY what to do.
For some reason the default config is not copied to the server by default. I don’t know why.
You’ll see the docker folders are empty, so create file: /opt/docker/ntfy/server.yml
Either paste the default config in there or only use the bits you need.
This is how ours is set:
# You need this to be your external domain to receive notifications while afh.
base-url: "https://ourntfy.ourdomain.com"
# If you use IOS then you need to include the following. Not needed for Android + PC
upstream-base-url: "https://ntfy.sh"
# This section creates the cache database and defines the length of time to hold messages
cache-file: /var/cache/ntfy/cache.db
cache-duration: "24h"
cache-startup-queries:
pragma journal_mode = WAL;
pragma synchronous = normal;
pragma temp_store = memory;
pragma busy_timeout = 15000;
vacuum;
# This creates a secondary database used to manage your users and permissions
auth-file: /var/cache/ntfy/auth.db
# auth-default-access: "read-write"
auth-default-access: "deny-all"
auth-startup-queries:
pragma journal_mode = WAL;
pragma synchronous = normal;
pragma temp_store = memory;
pragma busy_timeout = 15000;
vacuum;
# I assume you also need this for CloudFlared Tunnel (not sure), not just a ProxyManager.
behind-proxy: true
# Useful if you plan to send CCTV snapshots
attachment-cache-dir: "/var/cache/ntfy/attachments"
attachment-total-size-limit: "5G"
attachment-file-size-limit: "15M"
attachment-expiry-duration: "3h"
# Default if 15000. Reset to a safer limit for our restricted use.
global-topic-limit: 50
# Rate limiting in case a message source goes a bit nuts.
visitor-subscription-limit: 10
visitor-attachment-total-size-limit: "50M"
visitor-attachment-daily-bandwidth-limit: "100M"
The eagle eyed may have noticed this important entry in the system.yml
auth-default-access: “deny-all”
This prevents people without a uname/passwd from being able to use your NTFY should they stumble across the external URL.
Nice.
.
Step 5: Creating users and Topics
Now it’s restricted we need to create some users and specific access they need.
This bit is all in CLI within the container. Here we go…
To get to the command line within your NTFY container, SSH to your docker host and use the following command
docker exec -it ntfy sh
Now your’e in, these are a list of useful help commands.
clear ; ntfy --help
clear ; ntfy user --help
clear ; ntfy access --help
What we’ll do now is create 4 example users:
1 Admin so you can create and subscribe to any topic
1 Home Assistant user to send messages
1 “General” user to be able to receive “general” Home Assistant messages
1 “important” user to receive hi-pri messages
(Use a strong password for the HomeAssistant User)
ntfy user add --role=admin phil
ntfy user add homeassistantnotify
ntfy user add kids
ntfy user add adults
Now the users are created (and passwords set)
By default noone has rites to do anything, so we need to set HA to be able to send only (wo) and the users to receive only (ro)
As we do this, we’ll also be defining what Topics we’ll be using
- HomeAssistantGen
- HomeAssistantSOS
- FamilyChat
ntfy access homeassistantnotify HomeAssistantGen wo
ntfy access homeassistantnotify HomeAssistantSOS wo
ntfy access kids HomeAssistantGen ro
ntfy access kids FamilyChat rw
ntfy access adults HomeAssistantGen ro
ntfy access adults HomeAssistantSOS ro
ntfy access adults FamilyChat rw
.
Step 6: Mobile setup
The next step is to configure your mobile device(s) to receive notifications.
Install the NTFY app (Google or Apple)
First thing to do is go to the 3 dot “kebab” menu on the top right and goto Settings.
In General, Select Default Server and use your https://ourntfy.ourdomain.com.
Note: Each subscribed topic lets you override the defaults if needed.
Now hit the (+) and subscribe to your topic. No need to “use another server” as you already set your personal one as the default. Saves you having to type it in every time.
When you enter HomeAsssitantGen/SOS or FamilyChat you’ll be prompted (once) to enter your username. If you have the rites to subscribe to that topic then it’ll appear in the app.
If you can’t and it looks like it isn’t responding then check for typos or double check your permissions.
Note: Each device will have one user it can connect as.
Now your mobile device is set up, add the same topics in the web browser (as admin) and post a message in one of the topics. It should appear on a mobile device that has that topic subscribed.
If the mobile user is Read Only (ro) then they shouldn’t be able to post a message back.
This will keep the topic clear only for real alerts from Home Assistant.
.
Step 7: Home Assistant Config
After all that, this is the easy bit.
There’s no NTFY integration in Home assistant. What it uses is the Apprise integration as middleware to take the message, transform it to the right format and send it on to a recipient. This could be any of a plethora of destinations… one of which is NTFY
To start, lets set our secure data in secrets.yaml
If your Home Assistant is in the same LAN as the NTFY server, then use the NTFY local IP.
ntfy://{user}:{password}@{host}:{port}/{topics}
# NTFY example LAN
ntfy_url_1: ntfy://homeassistantnotify:[email protected]:8008/HomeAssistantGen
ntfy_url_2: ntfy://homeassistantnotify:[email protected]:8008/HomeAssistantSOS
For an external Home Assistant connecting using your full site URL (internet needed). Note it’s now ntfyS as it has an SSL certificate + no longer needs the port :8000 defined
ntfys://{user}:{password}@{host}/{topics}
# NTFY example WAN
ntfy_url_1: ntfys://homeassistantnotify:[email protected]/HomeAssistantGen
ntfy_url_2: ntfys://homeassistantnotify:[email protected]/HomeAssistantSOS
Now in the configuration.yaml
notify:
- name: ntfy_general_message
platform: apprise
url: !secret ntfy_url_1
- name: ntfy_sos_message
platform: apprise
url: !secret ntfy_url_2
.
Step 8: Test
Now create an automation or script and test the notification.
Something like this (run manually)
Script:
alias: Notification Test
sequence:
- service: notify.ntfy_general_message
data:
title: Test Message from Home Assistant
message: oooo the zigbeee
mode: single
icon: mdi:bullhorn
You can add priority levels for the HA notifications as well as icons and attach images, but the above is the basics just to get NTFY installed and running.
But that’s it, it’s in, it’s secure and most of all, it’s fast.
For the visual learners out there and to see how to do the cloudflared method for external access is setup (as well as some other NTFY use cases), check out NetWorkChuck’s video on NTFY.
None of the security elements are mentioned or creating the cache/user databases, but it’s still useful. 
