Utilities, checked 2026-10-17

ntfy: Docker configuration reference

Self-hosted pub-sub push notification service, driven by a simple HTTP API and topic subscriptions.

At a glance

Image: binwiederhier/ntfy
Tags: latest, v2.31.1, v2.31, v2
Licence: Apache-2.0
Source: https://github.com/binwiederhier/ntfy
Docs: https://docs.ntfy.sh/

Ports

Ports
Port	What listens	Source
`80`	Default HTTP listener, set with listen-http or the NTFY_LISTEN_HTTP environment variable.	source for port 80

Environment variables

Environment variables
Variable	Required	What it does	Example	Source
`NTFY_BASE_URL`	Yes	Public URL of the server. Required for attachments, email sending and iOS push, since it is used to build download and callback URLs.	`https://ntfy.example.com`	source for NTFY_BASE_URL
`NTFY_BEHIND_PROXY`	No	Tells ntfy to trust proxy headers for the visitor's real IP address, used for rate limiting.	`true`	source for NTFY_BEHIND_PROXY
`NTFY_CACHE_FILE`	No	SQLite file used to cache messages so subscribers can retrieve ones sent while they were offline.	`/var/cache/ntfy/cache.db`	source for NTFY_CACHE_FILE
`NTFY_AUTH_DEFAULT_ACCESS`	No	Default access policy applied to a topic with no explicit ACL entry. A private server should set this to deny-all rather than the open default.	`deny-all`	source for NTFY_AUTH_DEFAULT_ACCESS

Volumes that must persist

Volumes
Path	What is in it	Source
`/var/cache/ntfy`	Message cache and attachment storage, set by NTFY_CACHE_FILE and NTFY_ATTACHMENT_CACHE_DIR.	source for /var/cache/ntfy
`/etc/ntfy`	Server config file, user database and access control list when NTFY_AUTH_FILE is used.	source for /etc/ntfy

Behind a reverse proxy

Route the domain to container port 80, or the port from NTFY_LISTEN_HTTP. Set NTFY_BEHIND_PROXY so ntfy reads the real client IP from proxy headers instead of the proxy's own address. source for this reverse-proxy note
Subscriptions are long-lived streams and WebSockets. Forward the Upgrade and Connection headers and set a long proxy read timeout (the docs nginx example uses 3m). source for this reverse-proxy note
Set NTFY_BASE_URL to the public HTTPS address. Left unset or wrong, attachment download links and the topic URL in email footers point at the wrong host. source for this reverse-proxy note

Release timeline

Releases
Version	Date	Breaking	What changed	Source
`v2.31.1`	2026-10-17	No	Fixes the database load from since=message-ID reconnects with a new message cache index, and starts with a warning on a newer database schema.	source for release v2.31.1
`v2.31.0`	2026-10-15	No	Fixes messages lost when a client reconnects during publishing, and adds a ready endpoint for load balancers. Changes the experimental cluster schema.	source for release v2.31.0
`v2.30.0`	2026-10-12	No	Links attachments in email notifications, adds SMTP LOGIN auth and fixes PostgreSQL memory growth. Adds experimental clustering.	source for release v2.30.0
`v2.29.0`	2026-10-07	No	Fixes cache writes under load so delayed messages and polls are not missed, and adds timezone support for delayed notifications.	source for release v2.29.0
`v2.28.0`	2026-08-27	No	Hardening release bounding the cost of repeated poll requests without a since cursor and closing two unbounded fields.	source for release v2.28.0
`v2.27.0`	2026-08-04	No	Adds signing in with a verified email address instead of username, and hardens the message templating engine against memory exhaustion.	source for release v2.27.0
`v2.26.0`	2026-07-09	No	Hardens message templates with a hard execution timeout, closing a denial-of-service hole.	source for release v2.26.0
`v2.25.0`	2026-06-24	No	Adds password reset via email and reworks email verification to use durable link-based magic links.	source for release v2.25.0
`v2.24.0`	2026-06-04	No	Adds an in-memory ACL cache to reduce read load on the database from topic authorization checks.	source for release v2.24.0

If it is not coming up

Read from the upstream documentation, repository and container registry by Keita Emsden on 2026-10-17. Every row links the page it came from. Upstream changes without telling anyone, so check the source link before you rely on a value.

Other app references

All app references