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.

Note

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

Overview¶

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.

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:

Erstelle Ordner für Daten:

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

Configuration¶

Adjust the server configuration file ~/opt/ntfy/server/server.yml to match your environment:

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.

Service¶

Create a systemd service unit at ~/.config/systemd/user/ntfy.service:

[Unit]
Description=ntfy server
WantedBy=default.target

[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

Register and start the service

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

Verify it is running:

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

Web Access¶

Create a web backend to make the service available at [up.example.com](https://up.example.com]:

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

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 provide 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: "/"

After restarting the service, the web interface is available at up.example.com.

Backup¶

To back up the SQLite database(s) used by ntfy, back up the entire data folder ~/var/lib/ntfy. For instance, use tar:

tar -cf - ~/var/lib/ntfy | zstd - > ntfy.tar.zstd

Update¶

To update ntfy, download the new version and replace the executable:

[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.