ntfy¶

License: Apache License 2.0

This guide is tested with ntfy 2.28.0 on Uberspace 8.0.93. We can't guarantee it to work with newer versions.

Send push notifications to your phone or desktop using PUT/POST.

ntfy is an open-source push notification service that can be used as a UnifiedPush distributor with a companion Android App.

This guide installs the application at ~/opt/ntfy/ with the data stored at ~/var/lib/ntfy. The service is named “ntfy”, uses port 9009 internally and is exposed at up.example.com. It logs to the systemd journal.

Note

For this guide you should be familiar with the basic concepts of:

Installation¶

Download and install the linux-amd64 variant and extract it to ~/opt/ntfy:

[isabell@moondust ~]$ mkdir -p ~/opt/ntfy
[isabell@moondust ~]$ wget -O ntfy.tar.gz https://github.com/binwiederhier/ntfy/releases/download/v2.28.0/ntfy_2.28.0_linux_amd64.tar.gz
[isabell@moondust ~]$ tar --strip-components=1 -xzf ntfy.tar.gz -C ~/opt/ntfy/
[isabell@moondust ~]$ rm ntfy.tar.gz

Create folders to store the data in:

[isabell@moondust ~]$ mkdir -p ~/var/lib/ntfy/attachments/

Create a systemd service unit at ~/.config/systemd/user/ntfy.service with the following content:

[Unit]
Description=ntfy server

[Service]
WorkingDirectory=%h/opt/ntfy
ExecStart=%h/opt/ntfy/ntfy serve --no-log-dates --config %h/opt/ntfy/server/server.yml
ExecReload=/bin/kill --signal HUP $MAINPID
Restart=on-failure

[Install]
WantedBy=default.target

Add a domain and create a web backend to make the service available:

[isabell@moondust ~]$ uberspace web domain add up.example.com
[isabell@moondust ~]$ uberspace web backend add up.example.com port 9009

Do not forget to add the DNS entries!

Configuration¶

Adjust the server configuration file ~/opt/ntfy/server/server.yml to match your environment. Replace up.example.com with your domain and /home/isabell with your home directory:

base-url: https://up.example.com
listen-http: ":9009"
cache-file: /home/isabell/var/lib/ntfy/cache.db
auth-file: /home/isabell/var/lib/ntfy/auth.db
auth-default-access: "deny-all"
behind-proxy: true
attachment-cache-dir: "/home/isabell/var/lib/ntfy/attachments"
web-root: "disable"
log-level: error

Read through the configuration file and adjust any setting to your preference.

Reload systemd, enable the service for automatic startup, and start it now. This creates the authentication database needed by the user and permission commands below:

[isabell@moondust ~]$ systemctl --user daemon-reload
[isabell@moondust ~]$ systemctl --user enable --now ntfy
[isabell@moondust ~]$ systemctl --user status ntfy

Users and Permissions¶

Create an admin user:

[isabell@moondust ~]$ ~/opt/ntfy/ntfy user --config ~/opt/ntfy/server/server.yml add --role=admin isabell
[isabell@moondust ~]$ ~/opt/ntfy/ntfy user --config ~/opt/ntfy/server/server.yml list

UnifiedPush application servers need anonymous access. Grant it for topics prefixed with up:

[isabell@moondust ~]$ ~/opt/ntfy/ntfy access --config ~/opt/ntfy/server/server.yml '*' 'up*' write-only

Web Interface¶

ntfy provides a web interface which can be useful for testing purposes. To use it, the following setting has to be set in server.yml:

web-root: "/"

Restart the service to apply the change:

[isabell@moondust ~]$ systemctl --user restart ntfy

The web interface is available at up.example.com.

Backup¶

Stop ntfy while backing up the entire data folder ~/var/lib/ntfy so that its SQLite databases are not changing during the backup. Restart it afterwards:

[isabell@moondust ~]$ systemctl --user stop ntfy
[isabell@moondust ~]$ tar -cf - ~/var/lib/ntfy | zstd - > ntfy.tar.zstd
[isabell@moondust ~]$ systemctl --user start ntfy

Updates¶

Note

Check the release feed regularly for new versions.

To update ntfy, download the new version and replace the executable. Replace 2.28.0 in the commands below with the version you want to install:

[isabell@moondust ~]$ wget -O ntfy.tar.gz https://github.com/binwiederhier/ntfy/releases/download/v2.28.0/ntfy_2.28.0_linux_amd64.tar.gz
[isabell@moondust ~]$ tar --strip-components=1 -xzf ntfy.tar.gz -C ~/opt/ntfy/ ntfy_2.28.0_linux_amd64/ntfy
[isabell@moondust ~]$ rm ntfy.tar.gz

Finally, restart the service and check its status:

[isabell@moondust ~]$ systemctl --user restart ntfy
[isabell@moondust ~]$ systemctl --user status ntfy