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.
By Simon Vasconcelos Lee
Published on 21 November 202615-minute read
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.auth-default-access: deny-all, create an admin with ntfy user add, then give each script its own token and limited permissions.server.yml and user.db, which hold the configuration, users, permissions and tokens; update by changing the image tag, after reading the release notes.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.
curl, a script, a scheduled job or another application. A message can carry a title, a priority from 1 to 5, tags and emojis, an attachment, action buttons or a delayed delivery time.ntfy command line, or the API, over WebSocket or an HTTP stream that stays open.curl -d "Backup finished" https://ntfy.example.com/backups
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.
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:
nofile, allows. The package’s systemd service sets it to 10,000.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.
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:
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:
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
docker compose up -d
curl http://127.0.0.1:2586/v1/health
The server answers {"healthy":true,"role":"active"}. What each setting does:
127.0.0.1:2586: the documentation’s Docker examples publish port 80 on every address, and its reverse proxy examples forward to 127.0.0.1:2586. Published this way, the port can only be reached from the server itself, and the API is reached through the reverse proxy alone, over HTTPS.base-url: the public address of the service. The sample server.yml file requires it for attachments, sending email and iOS notifications from a self-hosted server.cache-file: without it, messages stay in memory for 12 hours and are lost on restart. This cache lets phones with a brittle connection fetch the messages they missed.attachment-cache-dir: enables attachments. ntfy takes full control of this folder, so keep it for this purpose only.auth-file and auth-default-access: deny-all: the user and permission database, created at first start, and anonymous access denied by default. This is the setting the documentation recommends for a private instance.behind-proxy: without it, behind a proxy, every visitor shares the proxy’s IP address and the same rate limits.enable-login: lets you log in to the web app. Open sign-up stays closed, since enable-signup defaults to false.v2.38.1 tag pins the version; latest follows the newest release. The documentation also offers user: UID:GID for a non-root account: the files in etc and lib then belong to it.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:
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".
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.
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.
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:
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
read-write, read-only, write-only or deny, on a specific topic or on a pattern such as alerts-*, the only wildcard supported.everyone, or *. For UnifiedPush on a private instance, the documentation opens the topics that start with up for writing only: ntfy access '*' 'up*' write-only.tk_, can expire with --expires=30d, and each user can keep up to 60 of them. ntfy token list shows them, ntfy token remove deletes one.auth-users, auth-access and auth-tokens create the same objects from server.yml, at every start. A user removed from that list is deleted from the database at the next restart.The script then publishes with its token, over HTTPS:
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.
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:
Upgrade and Connection headers, and lets these long connections live. ntfy sends a keepalive message every 45 seconds by default, keepalive-interval, so that no intermediary closes them for inactivity.behind-proxy: true, ntfy reads the X-Forwarded-For header and keeps the right-most address, the one your proxy adds. Rate limits apply to that address.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:
ntfy.example.com {
reverse_proxy 127.0.0.1:2586
}
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:
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;
}
}
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 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.
ntfy webpush keys and a valid HTTPS certificate.Add one line to server.yml, then restart the container:
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.
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:
| Setting | Default | What it limits |
|---|---|---|
visitor-request-limit-burst | 60 | A visitor’s requests in one burst |
visitor-request-limit-replenish | 5s | The refill rate: one request every 5 seconds |
visitor-subscription-limit | 30 | Open connections per visitor |
visitor-message-daily-limit | None | Messages per day, otherwise governed by the request limit |
visitor-email-limit-burst | 16 | Emails in one burst, then one per hour |
visitor-attachment-total-size-limit | 100M | Attachment storage per visitor |
visitor-attachment-daily-bandwidth-limit | 500M | Attachment traffic per visitor per day |
global-topic-limit | 15,000 | The server’s total number of topics |
message-size-limit | 4K | The size of a message; beyond it, it becomes an attachment |
visitor-request-limit-exempt-hosts, a list of IP addresses or hostnames.ntfy tier, give some accounts higher limits.attachment-file-size-limit, 15M by default, caps each file, attachment-total-size-limit, 5G, the whole store, and attachment-expiry-duration, 3h, their lifetime. An attachment never outlives its message: to keep attachments longer, raise cache-duration as well.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.
smtp-sender-addr: "smtp.example.com:587"
smtp-sender-user: "ntfy@example.com"
smtp-sender-pass: "smtp-password"
smtp-sender-from: "ntfy@example.com"
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
base-url and smtp-sender-from are required as soon as smtp-sender-addr is set: the server refuses to start without them.smtp-sender-verify: true restricts sending to the addresses each user has verified in their account, and closes it to anonymous users.server.yml: keep that file readable by its owner only, with chmod 600.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:
| Item | What it holds | Back it up |
|---|---|---|
etc/server.yml | The configuration, including SMTP secrets and Web Push keys | Yes |
lib/user.db | Users, access control entries, tokens and daily counts | Yes |
lib/cache.db | Messages from the last 12 hours, by default | Useful, its lifetime is short |
lib/attachments/ | Attachments from the last 3 hours, by default | Useful, its lifetime is short |
web-push-file file | Browsers’ Web Push subscriptions, if you enabled it | Yes |
For a consistent copy of the SQLite files, stop the service while the archive is made:
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.
With Docker, change the image tag in compose.yaml, for example from v2.38.1 to the next version, then:
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.
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.
| Topic | Our teams | You |
|---|---|---|
| The server | System and security updates, server interventions included | The timing that suits your business |
| Monitoring | Server monitored 24/7, with intervention without waiting for your call | Reading your instance’s logs |
| ntfy | Proactive monitoring: errors, slowdowns, open connections and disk space spotted, fix recommended | Its installation, updates and settings, which you apply, yourself or through your AI assistant |
| Access | The server that carries it, monitored and backed up | Users, topic permissions and your scripts’ tokens |
| Backups | Every night, encrypted and kept off the machine; restores included | ntfy’s own copies, and the restore request, when you need one |
| Migration | Your current server migrated, free of charge | The 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.
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 complimentary.
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.
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.
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.
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.
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.
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.
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.
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.
Simafri
Let's talk about your website
Tell us about your project in a few words: we will get back to you quickly.
Thank you! Your request has been sent. We'll get back to you shortly.
Prefer email? Write to us at support@simafri.com.