Ntfy is a free and open source notification service written in Go which lets us easily send and receive push notifications on smartphones or desktop computers via simple POST or PUT requests. The basic online service is publicly available free of charge and, on Linux, it is also possible to self-host an Ntfy instance.
In this tutorial we see how to install an Ntfy server on Linux and how to use it to send and receive push notifications.
In this tutorial you will learn:
- How to install the Ntfy repository on Debian-based systems
- How to install the Ntfy rpm package on Fedora-based distributions
- How to run Ntfy using the official Docker image
- How to subscribe to a topic and send notifications
| Category | Requirements, Conventions or Software Version Used |
|---|---|
| System | Distribution agnostic |
| Software | Ntfy, Docker (to run the Ntfy docker image) |
| Other | Root privileges |
| Conventions | # – requires given linux-commands to be executed with root privileges either directly as a root user or by use of sudo command$ – requires given linux-commands to be executed as a regular non-privileged user |
Installing the Ntfy repository (Debian-based systems)
The most straightforward way to install the Ntfy server on Debian-based distributions is by adding the official repository to the system software sources, and install the package containing the pre-compiled binary appropriate for the architecture of the machine we want to run the service on. Pre-compiled binaries exist for the following architectures:
- x86_64/amd64
- armv7/armhf
- arm64
The first thing we want to do is to add the repositories GPG key used to sign the repository packages to our system. The key can be downloaded with the following command:
$ curl -LO https://archive.heckel.io/apt/pubkey.txt
The key is ASCII armored: although on recent versions on Debian (since Debian Jessie) it is possible to use armored keys directly, to ensure the maximum compatibility, we need to dearmor it before copying it to the appropriate location. We can perform both operations by running:
$ sudo gpg --output /usr/share/keyrings/archive.heckel.io.gpg --dearmor pubkey.txt
With the key in place, we can add the repository to the distribution software sources. We create the /etc/apt/sources.list.d/archive.heckel.io.list file with the following content:
deb [arch=amd64 signed-by=/usr/share/keyrings/archive.heckel.io.gpg] https://archive.heckel.io/apt debian main
At this point we can update the package index files and install the ntfy package:
$ sudo apt-get update && sudo apt-get install ntfy
Installing the ntfy rpm package (Fedora-based distributions)
At the moment of writing, there is no rpm repository available, therefore, on Fedora-based distributions we have to install the official rpm package directly, with the following command:
$ sudo dnf install https://github.com/binwiederhier/ntfy/releases/download/v2.5.0/ntfy_2.5.0_linux_amd64.rpm
We will be prompted to confirm the installation. If everything looks OK, as it should, we can answer affirmatively:
============================================================================================================================ Package Architecture Version Repository Size ============================================================================================================================ Installing: ntfy x86_64 2.5.0-1 @commandline 20 M Transaction Summary ============================================================================================================================ Install 1 Package Total size: 20 M Installed size: 41 M Is this ok [y/N]: y
Configuring Ntfy and starting the service
Once Ntfy is installed, we can start the service and make so that it is automatically started at boot:
$ sudo systemctl enable --now ntfy
The ntfy service, when started, should work out of the box, listening on port 80. To tweak some configuration parameters, however, we must edit the
/etc/ntfy/server.yml file, where, among the other things, we can enable https support by using the listen-https directive to set the port we want to use (typically 443). When we do so, we must also specify the path of the key and of the cert files:
listen-https: ":443" key-file: /path/to/key-file cert-file: /path/to/cert-file
Many other parameters can be adjusted. The official documentation provides the complete list of config options.
Using the Docker image
By using the official Ntfy Docker image, we can run the service in a cross-distribution and isolated way. The image is available for the architectures we mentioned above, plus armv6: this makes possible to deploy the service also on early Raspberry Pi models. To download the Docker image and start a container based on it, we can use the following command:
$ sudo docker run -d -p 80:80 binwiederhier/ntfy serve
With the command above we run the container in detached mode (
-d) and map port 80 inside of it, to the same port on the host system. This is the simplest possible way to start the service. To use a modified configuration file, we must bind-mount its location on the host system to the appropriate place inside the container (bind-mounting the file we can see the changes we made inside of it, immediately reflected inside the container). Assuming the configuration file server.yml to be in the current working directory, we would run:
$ sudo docker run -d -p 80:80 -v "$(pwd)"/server.yml:/etc/ntfy/server.yml
Further examples of using the Docker image can be found on the official documentation page.
Subscribing to a topic and sending notifications
Once the server is accessible (be sure to configure your firewall so it allows traffic through the appropriate ports), we can use a client application to subscribe to a topic. Here is an example using the Android application, which is also free and open source software. On Android, the application can be installed from Google Play or from F-droid (on Apple devices it can be installed from the App Store):
To subscribe to a topic, we launch the application and tap on the “+” button:
We than write the name of a topic we want to subscribe to (the name is completely arbitrary), and, to use our self-hosted Ntfy instance, we check “Use another server” and enter the IP of our server; finally, we tap on “subscribe”. In this case, just as an example, I used an internal LAN server:
To send notification to the topic, all we have to do is to issue a POST or PUT request to the server, using our programming language of choice, or our favorite command line tool. In the example below, we use curl:
$ curl -d "Hello World!" http://192.168.0.39/linuxconfig
The push notification should appear on our client device:
Conclusions
In this tutorial we learned how to self-host an Ntfy server on Linux. Ntfy is free and open source software which allows us to subscribe to a topic of our choice and receive push notifications we can send via simple POST or PUT requests. You can learn more about the project on Github and by looking at the official documentation.