Ntfy: self-hosted notification service
Push notifications made easy
Content
Step 1 — Create the container
Step 2 — Make your first notification
Step 3 — Make your ntfy reachable from oustide
Step 4 — Install the mobile app
Step 5 — Config for iOS
Step 6 — Test
Step 7 — Security
Step 8 — Example of use
Conclusion
Introduction
Ntfy is a tool for sending push notifications via HTTP requests. Below you’ll find all the steps required to install and configure the product
Step 1 — Create the container
Create a user to run the container and keep its id and group in mind
adduser ntfy
id ntfy
Create the environment
mkdir -p ntfy/{cache,config,db}
chown -R ntfy ntfy
cd ntfy
Create the docker-compose.yml
file inside the ntfy folder
vim docker-compose.yml
version: "2.3"
services:
ntfy:
image: binwiederhier/ntfy
container_name: ntfy
command:
- serve
environment:
- TZ=UTC # optional: set desired timezone
user: 1003:1003 # replace with the user/group or uid/gid
volumes:
- ./cache:/var/cache/ntfy
- ./config:/etc/ntfy
- ./db:/var/lib/ntfy/
ports:
- 8000:80 # exposed on port 8000 (you can change it)
restart: unless-stopped
Now run the container
docker-compose up -d
Open your browser and get to the following page :
http://192.168.1.X:8000
Step 2 — Make your first notification
Run the following command to send a notification to your ntfy server specifying that we want to send a notification in the test channel using /test
in our command
curl -d "Hello World!" 192.168.1.X:8000/test
Then go back to the homepage and check if the notification has arrived
Huh, doesn’t look like.. But this is normal, because we need to add the test channel to our server so that it can receive notifications
To do that, press on + Subscribe to topic
button and add the test topic (channel) by finally pressing subscribe
Now you can see that we received the “Hello World!” notification from the curl
command
Step 3 — Make your ntfy reachable from oustide
For this you’ll need a domain name and an Nginx or an other Reverse Proxy
I won’t go into detail here on how to do this, you’ll find plenty of tutorials on the internet explaining how to do it. Suffice it to say that your domain name must point to your public ip. Once the domain name points to your public ip, you’ll need to set up a Reverse Proxy to link the domain name to the private ip of your ntfy machine (don’t forget that in addition to forwarding to the private ip, the Reverse Proxy need to connect to the correct port, in our case port 8000).
Personally, I use a Nginx Proxy Manager in this example, you can see a plan of my infrastructure in this article:
Once this is done, you should be able to make the curl command by replacing the private ip by your domain name:
curl -d "Hello World!" <your-domain-name.com>/test
Step 4 — Install the mobile app
To receive notifications sent to your server on your phone, you’ll need the ntfy app. You can install the app on App Store or on Google Play Store, here I’m going to install it on my iPhone
Configure the app
First, you’ll need to authorize the app to send you notification (I mean, that’s what it’s all about) then press Settings
and change the Default server
to your URL
Now go back to the Notifications
menu and press the plus button +
this will allow you to subscribe to a new topic, in our case, the test one
You can see that there’s already a notification in this topic, that’s normal, it’s our “Hello World!” test that we did before.
Step 5 — Config for iOS
Our current configuration does not yet allow us to receive notifications on an iOS device. New messages do appear in the mobile application’s topics, but no push notifications appear on iPhone (on Android they already work). For your iPhone to receive notifications correctly, we’ll need to change one of our ntfy configuration parameters.
Import configuration file
To do this, create a new file in the previously created config
folder
vim config/server.yml
Copy the default ntfy configuration file on their github directory
https://github.com/binwiederhier/ntfy/blob/main/server/server.yml
And paste it into the server.yml
file that you’ve just created
Modify configuration file
In the configuration file, we’ll need to change 2 things: the first is to uncomment the line containing base-url
and add your complete url with your domain name.
The second thing to change is the upstream-base-url
line, which just needs to be uncommented but not modified. It helps the iOS application send notifications. But don’t worry, ntfy won’t be able to read your messages, just the id of them.
Step 6 — Test
Now you can retry the curl
command from your computer and see that you receive the notification on your phone.
curl -d "Does it work?" <your-domain-name.com>/test
See? I receive the notification correctly
Step 7 — Security
For the time being, anyone can send notifications to your server simply by making a curl request. To make your server more secure, you can add authentication for topics
Edit the configuration file
Add the following lines to the server.yml
configuration file
auth-file: "/var/lib/ntfy/user.db"
auth-default-access: "deny-all"
Restart the container to apply the modifications
docker restart ntfy
Add an admin user
Connect into your ntfy container
docker exec -it ntfy sh
Once on the container shell, add an admin account using the ntfy command
ntfy user add --role=admin <username>
This will create an admin account that will have access to all topics
Test
Unsubscribe from test topic
Press Subscribe to topic
This will open a page asking you which topic you want to subscribe to. To create a new topic with a name of your choice you can enter it here, or if like me you prefer to have a topic with a random name for more security, click on generate
Since we’ve set up an admin account and we’ve configured all topics to deny all
by default, you’ll be asked to enter the credentials of the admin account you’ve created to access the topic
Press login and that’s it! You are now able to have username and password-protected topics
All you have to do now is change on the mobile application and you’ll have a perfect self hosted notification push tool
Mobile app
In the mobile application, go to the Settings
menu, then to + Add user
, register a new user by specify the URL of your instance, a username and a password. Then unsubscribe from the older saved topic and add the new one
Step 8 — Example of use
SSH login
Get a notification every time someone log into your machine
vim /etc/profile
if [ -n "$SSH_CLIENT" ]; then
curl -H "Title: SSH Login" -u "<username>:<password>" -d "${USER}@$(hostname -f) from $(echo $SSH_CLIENT|awk '{print $1}')" https://<your-domain-name.com/your-topic> > /dev/null 2>&1
fi
Minecraft server backup
Backup your Minecraft server and get a notification at 00h when it’s done with an info of the remaining space on the disk (note that if you want to do this you’ll have to change the $(df -hP | awk ‘NR==3 {print $4}’)
to choose the disk you want to monitor the space remaining)
vim /home/<your-user>/cron/script/backup_minecraft-srv.sh
cp -r /<your-path>/minecraftdata /<your-path>/backup_`date +%d-%m-%Y_%H:%M:%S`
crontab -e
0 0 * * * /home/<your-user>/cron/script/backup_minecraft-srv.sh && curl -u "<username>:<password>" -d "Backup Done (disk space avail: $(df -hP | awk 'NR==3 {print $4}'))" -H "Tags: white_check_mark" -H "Title: Minecraft server" https://<your-domain-name.com/your-topic>
Custom task text notification
If you want to have a quick command to send you a notification when a task is done by simply typing:
ntfy "<your-text-here>"
You’ll have to write a new alias
in your .bashrc
or .zshrc
if you’re using zsh
vim ./bashrc
alias ntfy='function _ntfy() { curl -u "<username>:<password>" -H "t: Task ✅" -d "$*" https://<your-domain-name.com/your-topic> > /dev/null 2>&1; }; _ntfy'
Now you can simply make a notification with a command like apt ugrade
sudo apt upgrade && ntfy "Upgrade done successfully"
Monitoring with Uptime Kuma
If you haven’t already seen it, I’ve put together a tutorial on setting up Uptime Kuma, an open source monitoring tool.
An example of using ntfy would be to link Uptime Kuma to your ntfy chanel, which would enable you to receive monitoring notifications directly on your devices.
Don’t worry, I’ve also made a tutorial on configuring Uptime Kuma with ntfy
More example
You can find many more examples on the official ntfy website
https://docs.ntfy.sh/examples/
Conclusion
So now you can create a notification for any event you want to monitor. Don’t hesitate to write a comment below this article if you have any questions about this project.