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

ntfy — homepage

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:

Grafana: monitor Nginx Proxy Manager website

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.

Uptime Kuma: self-hosted 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

Uptime Kuma: link to 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.