Utilities, checked 2026-09-07
ntfy: Docker configuration reference
Self-hosted pub-sub push notification service, driven by a simple HTTP API and topic subscriptions.
At a glance
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
- Live topic subscriptions are a long-poll or SSE stream, not a websocket. Give the proxy a long read timeout so it does not cut an idle subscription, and prefer HTTP/2 or a generous keepalive. 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.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-09-07. 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