Self-hosting ntfy on Debian with nginx

ntfy (pronounced notify) is a simple HTTP-based pub-sub notification service. It allows you to send notifications to your phone or desktop via scripts from any computer, and/or using a REST API. It’s infinitely flexible, and 100% free software.

Docs • GitHub

Prerequisites

1. Add DNS records for your subdomain
2. Set up Let’s Encrypt SSL certificates

Installation

{% %} This guide is for Debian-based systems using nginx. For other distributions, refer to the official installation guide. {% %}

Check the ntfy releases page for the latest version. Replace v2.28.0 in the following commands with the current version:

wget https://github.com/binwiederhier/ntfy/releases/download/v2.28.0/ntfy_2.28.0_linux_amd64.deb
sudo dpkg -i ntfy_*.deb
sudo systemctl enable ntfy
sudo systemctl start ntfy

For more installation options, refer to the official installation guide.

Configuration

Edit the config file:

sudo $EDITOR /etc/ntfy/server.yml

Add the following configuration (adjust as needed):

{% %} Replace $PORT and $USERNAME with your actual values. {% %}

base-url: "https://ntfy.osc.garden"
listen-http: "127.0.0.1:$PORT"
behind-proxy: true

# For iOS instant notifications.
upstream-base-url: "https://ntfy.sh"

# Persist messages on restart.
cache-file: "/var/cache/ntfy/cache.db"
cache-duration: "12h"

# For a private instance.
auth-file: "/var/lib/ntfy/user.db"
auth-default-access: "deny-all"

For a detailed explanation of these configuration options, see the server configuration documentation.

Start the ntfy server:

sudo ntfy serve

While serving, add an admin user:

sudo ntfy user add --role=admin $USERNAME

Nginx configuration

Add this server block to your Nginx configuration:

# ntfy notifications
server {
    listen 443 ssl http2;
    include /etc/nginx/include.d/all-common;
    server_name ntfy.osc.garden;
    location / {
        proxy_pass http://localhost:$PORT;
        proxy_http_version 1.1;

        proxy_set_header Host $http_host;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

        proxy_connect_timeout 3m;
        proxy_send_timeout 3m;
        proxy_read_timeout 3m;

        client_max_body_size 0; # Stream request body to backend
    }
}

This configuration is based on the recommended Nginx setup in the ntfy documentation.

Test and reload Nginx:

sudo nginx -t
sudo systemctl reload nginx

Access tokens

Create access tokens for different uses:

ntfy token add osc

Use these tokens to authenticate when publishing messages.

Updating ntfy

{% %} Review the release notes before updating to check for any breaking changes or new configuration options. {% %}

To update ntfy to a newer version, the process is similar to the initial installation:

1. Check for the latest version on the ntfy releases page

2. Download and install the new version:

   wget https://github.com/binwiederhier/ntfy/releases/download/v2.28.0/ntfy_2.28.0_linux_amd64.deb
   sudo dpkg -i ntfy_*.deb
   

3. Handle configuration file conflicts: You’ll be prompted about the configuration file if you’ve made changes:

   Configuration file '/etc/ntfy/server.yml'
    ==> Modified (by you or by a script) since installation.
    ==> Package distributor has shipped an updated version.
      What would you like to do about it ?  Your options are:
       Y or I  : install the package maintainer's version
       N or O  : keep your currently-installed version
         D     : show the differences between the versions
         Z     : start a shell to examine the situation
   

   After making your choice —I recommend N after reviewing with D—, ntfy should restart.

4. Verify the update:

   ntfy --version
   sudo systemctl status ntfy
   

Troubleshooting

• Check ntfy logs: journalctl -u ntfy
• Verify ntfy status: systemctl status ntfy
• Test ntfy directly: curl http://localhost:$PORT/health

For more advanced troubleshooting, consult the ntfy server documentation.