Self-host ntfy on a managed VPS: push notifications from your own server

When you self-host ntfy on a managed VPS, you send push notifications with a plain HTTP request, PUT or POST, from a machine of your own, which our teams keep up to date and monitor day and night. ntfy is free software, dual licensed under Apache 2.0 and GPLv2. This guide follows its official documentation at version 2.38.1: installing with Docker Compose, the server.yml file, users and access control, access tokens, HTTPS, the mobile apps, email, backups and updates.

Simon Vasconcelos Lee By Published on 21 November 202615 minute read

All guides

In short

  1. ntfy takes a message through an HTTP PUT or POST request to a topic, and pushes it straight away to the phones, browsers and scripts subscribed to that topic.
  2. Its dual license, Apache 2.0 and GPLv2, lets you run it freely at work; its conditions apply to redistributing the software.
  3. Install it with Docker Compose: the binwiederhier/ntfy image, a server.yml with base-url, cache-file and auth-file, and the port published on 127.0.0.1 behind an HTTPS reverse proxy.
  4. By default, everyone can read and write every topic: set auth-default-access: deny-all, create an admin with ntfy user add, then give each script its own token and limited permissions.
  5. Back up server.yml and user.db, which hold the configuration, users, permissions and tokens; update by changing the image tag, after reading the release notes.

What ntfy does

ntfy, pronounced "notify", is an HTTP-based publish-subscribe notification service. Its README presents it as a way to send notifications to your phone or desktop from scripts, from any computer. The project runs a public instance, ntfy.sh, and the server can be self-hosted: that is what this guide covers.

Terminal, a first message
curl -d "Backup finished" https://ntfy.example.com/backups

The Apache 2.0 and GPLv2 licenses, and the trademark

The ntfy README states that the project is dual licensed: under the Apache License 2.0, in the LICENSE file, and under the GNU GPL version 2, in LICENSE.GPLv2. The Docker image declares both, Apache-2.0, GPL-2.0.

Running ntfy on your server, for your company, your team or your clients, therefore needs no license to buy. Both texts provide the software without warranty.

The license covers the code. The name is a separate matter: the Apache License 2.0 grants no rights to the licensor’s trademarks, and the ntfy.sh terms of service state that the ntfy name, logo and branding are trademarks of ntfy LLC, whose use in connection with a product or service requires its prior written consent. This guide names ntfy to describe the software.

This publication is independent of the ntfy project and of ntfy LLC, and is not affiliated with, sponsored or approved by them.

Resources to plan for

The server is a single, statically linked binary for amd64, armv7 and arm64; the Docker image is also available for armv6. The documentation gives no figures for memory or CPU: for a home server, it says, scale is nothing to worry about. Instead, it points to what limits an instance:

On a managed VPS, tell us about your usage, the number of subscribed devices, the volume of messages and the attachments, and we will recommend the right size.

Installing with Docker Compose

The documentation offers the binwiederhier/ntfy image from Docker Hub. It serves the web app and the API on the container’s port 80, and contains no server.yml file: the configuration goes in a folder mounted on /etc/ntfy. On a server with Docker installed, create a folder and put this compose.yaml in it, based on the documentation’s example:

compose.yaml
services:
  ntfy:
    image: binwiederhier/ntfy:v2.38.1
    container_name: ntfy
    command:
      - serve
    environment:
      - TZ=UTC
    volumes:
      - ./etc:/etc/ntfy
      - ./lib:/var/lib/ntfy
    ports:
      - "127.0.0.1:2586:80"
    healthcheck:
      test: ["CMD-SHELL", "wget -q --tries=1 http://localhost:80/v1/health -O - | grep -Eo '\"healthy\"\\s*:\\s*true' || exit 1"]
      interval: 60s
      timeout: 10s
      retries: 3
      start_period: 40s
    restart: unless-stopped
    init: true

Then the configuration file, in etc/server.yml, with your server’s public address:

etc/server.yml
base-url: "https://ntfy.example.com"
cache-file: "/var/lib/ntfy/cache.db"
attachment-cache-dir: "/var/lib/ntfy/attachments"
auth-file: "/var/lib/ntfy/user.db"
auth-default-access: "deny-all"
behind-proxy: true
enable-login: true
Terminal, in the compose.yaml folder
docker compose up -d
curl http://127.0.0.1:2586/v1/health

The server answers {"healthy":true,"role":"active"}. What each setting does:

Without Docker: the Debian and Ubuntu repository

The project also publishes a package repository, signed with the key fingerprint 55BA 774A 6F5E E674 31E4 B6B7 CFDB 962D 4F1E C4AF. On an amd64 server:

Terminal
sudo mkdir -p /etc/apt/keyrings
sudo curl -L -o /etc/apt/keyrings/ntfy.gpg https://archive.ntfy.sh/apt/keyring.gpg
sudo apt install apt-transport-https
echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/ntfy.gpg] https://archive.ntfy.sh/apt stable main" \
    | sudo tee /etc/apt/sources.list.d/ntfy.list
sudo apt update
sudo apt install ntfy
sudo systemctl enable ntfy
sudo systemctl start ntfy

The package reads /etc/ntfy/server.yml. The sample file recommends /var/cache/ntfy/cache.db for the cache and /var/lib/ntfy/user.db for users, two folders the package creates. Behind a proxy, add listen-http: "127.0.0.1:2586".

Users, access control and tokens

Out of the box, an ntfy server is open: everyone can read and write every topic, and the topic name acts as the password. With auth-file and deny-all, nothing gets through without credentials. ntfy has two roles: admin, which reads and writes every topic, and user, which only has the permissions you grant it.

Terminal, the first admin
docker compose exec ntfy ntfy user add --role=admin alice

The command asks for the password, then for its confirmation. The ntfy user, ntfy access and ntfy token commands write directly to the user database: they run on the server, here inside the container, which reads the path of that database from server.yml.

One user and one token per script

An access token currently grants full access to its user’s account, except changing the password and deleting the account. For a script, create a dedicated user, limited to its topics, then a token for it:

Terminal
docker compose exec ntfy ntfy user add backup-server
docker compose exec ntfy ntfy access backup-server backups write-only
docker compose exec ntfy ntfy token add --label="backups" backup-server

The script then publishes with its token, over HTTPS:

Terminal, on the machine that publishes
curl \
  -H "Authorization: Bearer tk_AgQdq7mVBoFD37zQVN29RhuMzNIz2" \
  -H "Title: Backup finished" \
  -H "Priority: high" \
  -d "The nightly backup went fine." \
  https://ntfy.example.com/backups

A Basic auth password is only base64 encoded, not encrypted: the documentation asks for HTTPS on every self-hosted server. That is what the next section covers.

HTTPS: the reverse proxy

ntfy can serve HTTPS itself, but behind a proxy the documentation recommends leaving TLS termination to the proxy. Two points matter more than anything else:

With Caddy

The documentation notes that Caddy handles both HTTP and WebSockets with reverse_proxy, with no extra settings. It gets the Let’s Encrypt certificate on its own:

Caddyfile
ntfy.example.com {
    reverse_proxy 127.0.0.1:2586
}

With Nginx

This block follows the documentation’s configuration, close to the one ntfy.sh runs: buffering turned off for the streams, 3 minute timeouts, and no size limit on request bodies, which ntfy caps itself. It listens on port 80 so that Certbot can set up HTTPS:

/etc/nginx/sites-available/ntfy
server {
    listen 80;
    listen [::]:80;
    server_name ntfy.example.com;

    location / {
        proxy_pass http://127.0.0.1:2586;
        proxy_http_version 1.1;

        proxy_buffering off;
        proxy_request_buffering off;
        proxy_redirect off;

        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;
    }
}
Terminal
sudo ln -s /etc/nginx/sites-available/ntfy /etc/nginx/sites-enabled/
sudo nginx -t
sudo certbot --nginx -d ntfy.example.com

Once HTTP redirects to HTTPS, publish to https:// addresses in your scripts. For thousands of subscribers, the documentation raises worker_connections in nginx.conf and the Nginx service’s LimitNOFILE, to double the connections you are aiming for.

The Android, iOS and web apps

The ntfy apps add topics from your server just as they do from ntfy.sh: enter its address when you add the topic, and for a protected topic, the username and password of a user who has access to it. The web app is served at the server’s own address.

Instant notifications on iOS

Add one line to server.yml, then restart the container:

etc/server.yml
upstream-base-url: "https://ntfy.sh"

For every message, your server then publishes a poll request to ntfy.sh, which contains only the message ID and the SHA-256 hash of the topic URL. ntfy.sh passes it on to the device through Apple’s notification service, then the app fetches the message from your server. The text that goes through ntfy.sh is always the same, "New message", whatever yours says. Without this setting, notifications still arrive, with a delay that can reach several hours depending on the state of the phone. upstream-access-token adds a token if you exceed the ntfy.sh rate limits.

Rate limits and attachments

ntfy limits each visitor, identified by its IP address, and for IPv6 by its /64 subnet. These limits protect the server from abuse; in normal use, the documentation says you should not run into them. Past them, the server answers 429 Too Many Requests. The defaults:

SettingDefaultWhat it limits
visitor-request-limit-burst60A visitor’s requests in one burst
visitor-request-limit-replenish5sThe refill rate: one request every 5 seconds
visitor-subscription-limit30Open connections per visitor
visitor-message-daily-limitNoneMessages per day, otherwise governed by the request limit
visitor-email-limit-burst16Emails in one burst, then one per hour
visitor-attachment-total-size-limit100MAttachment storage per visitor
visitor-attachment-daily-bandwidth-limit500MAttachment traffic per visitor per day
global-topic-limit15,000The server’s total number of topics
message-size-limit4KThe size of a message; beyond it, it becomes an attachment

Email notifications

ntfy can forward a message by email when the publish request carries the Email header, or X-Email, with an address. To do so it goes through an outgoing SMTP server, over STARTTLS, with PLAIN or LOGIN authentication: that is port 587. From a Simafri VPS, email goes out through an authenticated SMTP relay on that same port 587: configure here the address of an email account you already have, or that of your email delivery service.

etc/server.yml
smtp-sender-addr: "smtp.example.com:587"
smtp-sender-user: "ntfy@example.com"
smtp-sender-pass: "smtp-password"
smtp-sender-from: "ntfy@example.com"
Terminal
curl \
  -H "Authorization: Bearer tk_AgQdq7mVBoFD37zQVN29RhuMzNIz2" \
  -H "Email: alice@example.com" \
  -d "The file server disk is over 90% full." \
  https://ntfy.example.com/alerts

Backups

With SQLite, ntfy keeps each kind of data in its own file. In this guide’s installation, everything sits in the etc and lib folders, next to the compose.yaml:

ItemWhat it holdsBack it up
etc/server.ymlThe configuration, including SMTP secrets and Web Push keysYes
lib/user.dbUsers, access control entries, tokens and daily countsYes
lib/cache.dbMessages from the last 12 hours, by defaultUseful, its lifetime is short
lib/attachments/Attachments from the last 3 hours, by defaultUseful, its lifetime is short
web-push-file fileBrowsers’ Web Push subscriptions, if you enabled itYes

For a consistent copy of the SQLite files, stop the service while the archive is made:

Terminal, in the compose.yaml folder
docker compose stop
tar -czf ntfy-$(date +%F).tar.gz compose.yaml etc lib
docker compose start

Schedule this copy at a quiet hour, and send it off the server. Stored on its disk, these archives are also part of its nightly backups. To restore, put the folders back in place, then run docker compose up -d.

If you lose user.db with no copy, the users and tokens declared in server.yml through auth-users and auth-tokens are recreated at startup; the ones created on the command line need to be created again.

Updates

With Docker, change the image tag in compose.yaml, for example from v2.38.1 to the next version, then:

Terminal, in the compose.yaml folder
docker compose pull
docker compose up -d

The etc and lib folders stay in place, and ntfy migrates its databases itself at startup. With the Debian package, sudo apt update then sudo apt upgrade do the same.

Each version’s notes, on the documentation’s "Releases" page, group under "Upgrade notes" what changes for an existing instance, such as, in 2.36.0, a configuration now fully checked at startup, or daily counts reset to zero. Read them before updating, and copy both folders right before. Version 2.38.1 is a security release, which the project strongly recommends: it hardens message templating against denial-of-service attacks, and keeps slow S3 attachment uploads and unresponsive web push endpoints from tying up memory and connections. It follows 2.38.0, which shares rate limits across the nodes of a cluster and is built with Go 1.27.4.

Who does what on a managed VPS

Self-hosting means running the server on top of the application. On a managed VPS, our teams take charge of the server and proactively monitor your instance; ntfy remains your software, with its settings and its data.

TopicOur teamsYou
The serverSystem and security updates, server interventions includedThe timing that suits your business
MonitoringServer monitored 24/7, with intervention without waiting for your callReading your instance’s logs
ntfyProactive monitoring: errors, slowdowns, open connections and disk space spotted, fix recommendedIts installation, updates and settings, which you apply, yourself or through your AI assistant
AccessThe server that carries it, monitored and backed upUsers, topic permissions and your scripts’ tokens
BackupsEvery night, encrypted and kept off the machine; restores includedntfy’s own copies, and the restore request, when you need one
MigrationYour current server migrated, free of chargeThe timing of the switch

If you would rather have our teams work inside the application itself, that service is billed by the hour or at a fixed rate, with an estimate shared before the work starts.

ntfy, on a server run for you

With a Simafri Managed VPS, our teams keep your ntfy instance’s server up to date, monitor it day and night and step in without waiting for your call; they also proactively monitor your instance and recommend useful fixes, which you apply, yourself or through your AI assistant. Backups are encrypted every night and kept off the machine, restores are included, and migrating your current server is free.

Explore Managed VPS

Frequently asked questions

Is ntfy free for a business?

Yes. ntfy is dual licensed under Apache 2.0 and GPLv2: you can run it at work with no license to buy. Their conditions apply to redistributing the software. What remains is the cost of the server that runs it.

How do I install ntfy with Docker Compose?

Create a compose.yaml with the binwiederhier/ntfy image, the serve command, a folder mounted on /etc/ntfy for server.yml, another on /var/lib/ntfy for the databases, and the container’s port 80 published on 127.0.0.1:2586. Run docker compose up -d, then put an HTTPS reverse proxy in front of that port.

How do I make an ntfy server private?

In server.yml, set auth-file and auth-default-access: deny-all. Then create an admin with ntfy user add --role=admin, limited users with ntfy user add, and their topic permissions with ntfy access.

How do I publish to ntfy from a script with a token?

Create a token with ntfy token add for a user dedicated to the script, limited to its topics, then publish with curl and the Authorization: Bearer header followed by the token, over HTTPS. A token grants access to its user’s whole account.

Why set behind-proxy in ntfy?

Behind a reverse proxy, every request comes from the proxy’s address. With behind-proxy: true, ntfy reads the X-Forwarded-For header to identify each visitor; without it, they all share the same rate limits.

Do ntfy notifications reach an iPhone right away?

Yes, with upstream-base-url: "https://ntfy.sh" in server.yml. Your server then has ntfy.sh relay a signal that contains only the message ID, and the app fetches the message from your server. Without this setting, delivery can take several hours.

How do I back up ntfy?

Back up server.yml and user.db, which hold the configuration, users, permissions and tokens, plus the Web Push file if it is enabled. The message cache and attachments have a short lifetime. Stop the service while you copy, for consistent SQLite files.

Does a managed VPS cover ntfy?

A managed VPS covers the server: system, security, monitoring and backups. Our teams also proactively monitor your instance and recommend useful fixes, which you apply. Work inside the application is billed by the hour or at a fixed rate.

Contact us