How to install and self host an Ntfy server on Linux

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
How to self host an Ntfy server on Linux
How to self host an Ntfy server on Linux
Software Requirements and Linux Command Line Conventions
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

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/ --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/ file with the following content:

deb [arch=amd64 signed-by=/usr/share/keyrings/] 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

We will be prompted to confirm the installation. If everything looks OK, as it should, we can answer affirmatively:

 Package                   Architecture                Version                      Repository                         Size
 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):

The ntfy app can on Google Play
The Ntfy app on Google Play

To subscribe to a topic, we launch the application and tap on the “+” button:

Tap on the "+" button to subscribe to a topic
Tap on the “+” button to subscribe to a topic

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:

Subscribing to a topic on our self-hosted Ntfy instance
Subscribing to a topic on our self-hosted Ntfy instance

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!"

The push notification should appear on our client device:

The push notification with the message we sent
The push notification with the message we sent


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.