Open Source: ntfy
In this article, we will go through a tool called ntfy, an open-source tool that is an HTTP-based pub-sub notification service. It allows you to send notifications to varioys clients using their simple REST API, or using their CLI tool.
Prerequisites
In order to complete this tutorial, you will need the following:
- Ubuntu or Debian machine
I am personally using the desktop version of Ubuntu 22.04.
Installation
While they offer a cloud version for as low as $5 per month for over 2000 messages a day, we will be running it locally.
There are multiple methods to download and install ntfy. One methods is to simply download the pre-built binary from their github repository. Another method is to install it by using the Debian repository. The method we will use to deploy the ntfy server, is by deplying a Docker container using the pre-built Docker image.
Note: if you are unfamiliar with Docker Images, check out this tutorial: https://hazemhadi.com/articles/docker-images-what-you-need-to-know/
To do that, simply run the following command:
docker run -p 8080:80 -it binwiederhier/ntfy serve
This will pull the Docker image and run the ntfy server on port 8080. Once it is done pulling, it should start running the application since we provided the serve command-line argument.
This will also provide you with a Web interface to view all notifications received and allow you to publish notifications.
How It Works
Before we move on any further, we need to understand what Pub-Sub means. Pub-Sub is short for Publisher-Subscriber which is a method of communication in which there is a server acting as a Publisher which sends messages on a topic. A subscriber (or subscribers) can then Subscribe to a topic to then receive any messages sent out by the Publisher.
Let us take an example to make it easier. Say you subscribed to a Newsletter. This Newsletter then send out an Email to all its subscribers, since you subscribed to the Newsletter, you will also receive an email. In this case, the Newsletter was the topic, the email was the message, you were the subscriber, and the service sending the email is the publisher.
Now, we can move on to sending and receiving messages.
Receiving Messages
There are multiple ways for you to receive messages sent through ntfy, these include:
- Receiving on your phone (Android or iPhone) using their app
- Receiving on a Web app
- Receiving on your Desktop
- Receiving on the CLI tool
- Receiving using the API
We will use the Web app for simplicity, but you can also try the other methods, such as receiving on your phone:
https://docs.ntfy.sh/subscribe/phone/
To receive messages on the Web app. Simply navigate to http://localhost:8080. This is a web app that was also launched as part of the Docker container we ran in the previous step. From here, we can both publish messages, and receive messages.
To receive a message, click on Subscribe to topic. This will prompt you to insert the name of the topic, we can simply use test.
Note: when using the cloud version, or if your instance was publicly accessible, you should use more secure and complicated names to prevent unauthorized access.
The web app will then display an interface similar to that of chat applications. From here, you can receive messages.
Publishing Messages:
There are a couple of methods to publish a message to a topic, these include sending an HTTP request or using the CLI.
For this example, we will use curl for its simplicity. To send a message using curl, run the following command:
curl -d "My First Message" http://localhost:8080/test
This will send the message “My First Message” to your local instance of ntfy on http://localhost:8080 and on the test topic.
You should get a JSON output that includes an ID, Timestamp, Expiry Timestamp, Event Type, Topic, and Message.
To view the message, head back to the web interface at http://localhost:8080/test. You should see a notification on the chat interface with your message!
You can play around by sending more messages and adding more subscribers!
Conclusion
Ntfy is a great tool for sending messages and notifications to multiple clients at the same time. You can even use it to set custom notification. For example, you can send a message to a topic if a script went wrong, or as a reminder for you to do something. It provides a simple and easy-to-use API and web and mobile phone interfaces.
I hope you enjoyed this article and benefitted from it. See you in the next one!