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

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

wget https://github.com/binwiederhier/ntfy/releases/download/v2.14.0/ntfy_2.14.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):

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

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.14.0/ntfy_2.14.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.